![]() | This article needs additional citations for verification. Please help improve this article by adding citations to reliable sources. Unsourced material may be challenged and removed. Find sources: "Self-documenting code" – news · newspapers · books · scholar · JSTOR (March 2020) (Learn how and when to remove this message) |
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. In web development, self-documenting refers to a website that exposes the entire process of its creation through public documentation, and whose public documentation is part of the development process.
Commonly stated objectives for self-documenting systems include:
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.
There are certain practical considerations that influence whether and how well the objectives for a self-documenting system can be realized.
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; }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.
![]() | This programming-language-related article is a stub. You can help Wikipedia by expanding it. |