Self-documenting code
Source code written to enable use by others without prior experience
In computer programming, self-documenting (or self-describing) source code and user interfaces follow naming conventions and structured programming conventions that enable use of the system without prior specific knowledge.
01Objectives
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 software manuals
- Facilitate automation through self-contained knowledge representation
02Conventions
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.
03Practical 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
04Examples
Below is a very simple example of self-documenting C 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; }05Criticism
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.
Sources and credits
This article is adapted from the Wikipedia article “Self-documenting code”, written by its contributors and licensed under CC BY-SA 4.0. Fathomly has changed the layout, removed citation markers, navigation and maintenance notices, and adjusted punctuation. This adapted version is shared under the same license. For references, see the original article.
Fathomly is not affiliated with or endorsed by the Wikimedia Foundation. Spotted a problem? Tell us.
