Self-documenting code
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.[1][2][3] 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.[4]
Self-documenting code most prominently, perhaps notoriously, uses very long names - that is to say, whole sentences - for variables, classes, and other identifiers. Whereas a variable or property may be simply "i" or "x" in conventional code, a whole-sentence name such as "WhichRowOfTheTableWeAreGenerating" or "theIndexOfTheLastItemWeWillProcess" would be used in self-documenting code.
Contents
Objectives
Lua error in package.lua at line 80: module 'strict' not found. 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
Conventions
Lua error in package.lua at line 80: module 'strict' not found. 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 numberOfWordsInThisArticle 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
Lua error in package.lua at line 80: module 'strict' not found. 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
See also
References
- ↑ Lua error in package.lua at line 80: module 'strict' not found.
- ↑ Lua error in package.lua at line 80: module 'strict' not found.
- ↑ (See e.g., Use–mention distinction, Naming collision, Polysemy)
- ↑ Lua error in package.lua at line 80: module 'strict' not found.
External links
- Jef Raskin on Self-documenting code: http://acmqueue.com/modules.php?name=Content&pa=showpage&pid=290&page=1.
- Steve McConnell's High Quality Routines checklist in his book Code Complete helps to facilitate the creation of self-documenting code.
<templatestyles src="Asbox/styles.css"></templatestyles>
 |
This programming-language-related article is a stub. You can help Wikipedia by expanding it. |
