In computer programming, self-documenting (or self-describing) is a common descriptor for source code and user interfaces that follow certain loosely defined conventions for naming and structure. These conventions are intended to enable developers, users, and maintainers of a system to use it effectively without requiring previous knowledge of its specification, design, or behavior.
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
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.
There are certain practical considerations that influence whether and how well the objectives for a self-documenting system can be realized.
- Code readability
- Literate Programming
- Natural language programming
- Inform 7, a programming language that is also a subset of English
- Attempto Controlled English, a subset of English that is also a knowledge representation language
- Autological word
- 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.
|This programming language–related article is a stub. You can help Wikipedia by expanding it.|