In computer programming, self-documenting (or self-describing) source code and follow naming conventions and structured programming conventions that enable use of the system without prior specific knowledge.
Objectives
Commonly stated objectives for self-documenting systems include:
-
Make source code easier to read and understand
-
Minimize the effort required to maintain or extend legacy systems
-
Reduce the need for users and developers of a system to consult secondary documentation sources such as code comments or
-
Facilitate automation through self-contained knowledge representation
Conventions
Self-documenting code is ostensibly written using human-readable names, typically consisting of a phrase in a human language which reflects the symbol's meaning, such as
article.numberOfWords or
TryOpen. The code must also have a clear and clean structure so that a human reader can easily understand the algorithm used.
Practical considerations
There are certain practical considerations that influence whether and how well the objectives for a self-documenting system can be realized.
-
uniformity of naming conventions
-
consistency
-
scope of the application and system requirements
Examples
Below is a very simple example of self-documenting code, using naming conventions in place of explicit comments to make the logic of the code more obvious to human readers.
size_t count_alphabetic_chars(const char *text)
{
if (text == NULL)
return 0;
size_t count = 0;
while (*text != '\0')
{
if (is_alphabetic(*text))
count++;
text++;
}
return count;
}
Criticism
Jef Raskin criticized the belief in "self-documenting" code by saying that code cannot explain the rationale behind why the program is being written or why it is implemented in such a way.
See also
Further reading
