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. 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.

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 software manuals
• 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 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

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

• Autological word
• Code readability
• Controlled natural language
• Literate programming
• Natural language programming

External links

• Jef Raskin on Self-documenting code: https://web.archive.org/web/20050505065105/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.