The principle of natural naming in software documentation

Kari Laitinen

Research output: Book/ReportReportProfessional

Abstract

The understandability of source programs and other types of software documents is important for several reasons. Software developers have to read documents written by their colleagues during reviews and software maintainers often need to study old source programs about which they have no previous knowledge. Naming is one important factor that affects how understandable source programs are. The principle of natural naming means that program elements such as variables, constants, tables, and functions should be named using whole natural words of a natural language with respect to the grammatical rules of the same natural language. Natural naming thus involves reducing risks of misunderstanding by avoiding abbreviations which are rather common in programming. This thesis introduces a set of natural naming principles for different types of program elements, and a method by which one can assure that the natural names used in source programs are consistent with written texts in other types of software documents such as requirement definitions. The natural naming principles have been taught to several groups of software developers, who were questioned afterwards in order to assess the usefulness of the naming principles. The feedback received from software developers is analyzed in this thesis. The results indicate that natural naming principles should be favoured in practical software development work.
Original languageEnglish
Place of PublicationEspoo
PublisherVTT Technical Research Centre of Finland
Number of pages88
ISBN (Print)951-38-4432-3
Publication statusPublished - 1993
MoE publication typeNot Eligible

Publication series

NameVTT Tiedotteita - Meddelanden - Research Notes
PublisherVTT
No.1498
ISSN (Print)1235-0605
ISSN (Electronic)1455-0865

Fingerprint

Software engineering
Feedback

Keywords

  • software engineering
  • system documentation
  • programming
  • human factors

Cite this

Laitinen, K. (1993). The principle of natural naming in software documentation. Espoo: VTT Technical Research Centre of Finland. VTT Tiedotteita - Meddelanden - Research Notes, No. 1498
Laitinen, Kari. / The principle of natural naming in software documentation. Espoo : VTT Technical Research Centre of Finland, 1993. 88 p. (VTT Tiedotteita - Meddelanden - Research Notes; No. 1498).
@book{06cb483553e94357877fcd994b560bd3,
title = "The principle of natural naming in software documentation",
abstract = "The understandability of source programs and other types of software documents is important for several reasons. Software developers have to read documents written by their colleagues during reviews and software maintainers often need to study old source programs about which they have no previous knowledge. Naming is one important factor that affects how understandable source programs are. The principle of natural naming means that program elements such as variables, constants, tables, and functions should be named using whole natural words of a natural language with respect to the grammatical rules of the same natural language. Natural naming thus involves reducing risks of misunderstanding by avoiding abbreviations which are rather common in programming. This thesis introduces a set of natural naming principles for different types of program elements, and a method by which one can assure that the natural names used in source programs are consistent with written texts in other types of software documents such as requirement definitions. The natural naming principles have been taught to several groups of software developers, who were questioned afterwards in order to assess the usefulness of the naming principles. The feedback received from software developers is analyzed in this thesis. The results indicate that natural naming principles should be favoured in practical software development work.",
keywords = "software engineering, system documentation, programming, human factors",
author = "Kari Laitinen",
year = "1993",
language = "English",
isbn = "951-38-4432-3",
series = "VTT Tiedotteita - Meddelanden - Research Notes",
publisher = "VTT Technical Research Centre of Finland",
number = "1498",
address = "Finland",

}

Laitinen, K 1993, The principle of natural naming in software documentation. VTT Tiedotteita - Meddelanden - Research Notes, no. 1498, VTT Technical Research Centre of Finland, Espoo.

The principle of natural naming in software documentation. / Laitinen, Kari.

Espoo : VTT Technical Research Centre of Finland, 1993. 88 p. (VTT Tiedotteita - Meddelanden - Research Notes; No. 1498).

Research output: Book/ReportReportProfessional

TY - BOOK

T1 - The principle of natural naming in software documentation

AU - Laitinen, Kari

PY - 1993

Y1 - 1993

N2 - The understandability of source programs and other types of software documents is important for several reasons. Software developers have to read documents written by their colleagues during reviews and software maintainers often need to study old source programs about which they have no previous knowledge. Naming is one important factor that affects how understandable source programs are. The principle of natural naming means that program elements such as variables, constants, tables, and functions should be named using whole natural words of a natural language with respect to the grammatical rules of the same natural language. Natural naming thus involves reducing risks of misunderstanding by avoiding abbreviations which are rather common in programming. This thesis introduces a set of natural naming principles for different types of program elements, and a method by which one can assure that the natural names used in source programs are consistent with written texts in other types of software documents such as requirement definitions. The natural naming principles have been taught to several groups of software developers, who were questioned afterwards in order to assess the usefulness of the naming principles. The feedback received from software developers is analyzed in this thesis. The results indicate that natural naming principles should be favoured in practical software development work.

AB - The understandability of source programs and other types of software documents is important for several reasons. Software developers have to read documents written by their colleagues during reviews and software maintainers often need to study old source programs about which they have no previous knowledge. Naming is one important factor that affects how understandable source programs are. The principle of natural naming means that program elements such as variables, constants, tables, and functions should be named using whole natural words of a natural language with respect to the grammatical rules of the same natural language. Natural naming thus involves reducing risks of misunderstanding by avoiding abbreviations which are rather common in programming. This thesis introduces a set of natural naming principles for different types of program elements, and a method by which one can assure that the natural names used in source programs are consistent with written texts in other types of software documents such as requirement definitions. The natural naming principles have been taught to several groups of software developers, who were questioned afterwards in order to assess the usefulness of the naming principles. The feedback received from software developers is analyzed in this thesis. The results indicate that natural naming principles should be favoured in practical software development work.

KW - software engineering

KW - system documentation

KW - programming

KW - human factors

M3 - Report

SN - 951-38-4432-3

T3 - VTT Tiedotteita - Meddelanden - Research Notes

BT - The principle of natural naming in software documentation

PB - VTT Technical Research Centre of Finland

CY - Espoo

ER -

Laitinen K. The principle of natural naming in software documentation. Espoo: VTT Technical Research Centre of Finland, 1993. 88 p. (VTT Tiedotteita - Meddelanden - Research Notes; No. 1498).