In
computer programming
Computer programming or coding is the composition of sequences of instructions, called computer program, programs, that computers can follow to perform tasks. It involves designing and implementing algorithms, step-by-step specifications of proc ...
, self-documenting (or self-describing)
source code
In computing, source code, or simply code or source, is a plain text computer program written in a programming language. A programmer writes the human readable source code to control the behavior of a computer.
Since a computer, at base, only ...
and
user interface
In the industrial design field of human–computer interaction, a user interface (UI) is the space where interactions between humans and machines occur. The goal of this interaction is to allow effective operation and control of the machine fro ...
s follow
naming conventions and
structured programming Structured programming is a programming paradigm aimed at improving the clarity, quality, and development time of a computer program by making specific disciplined use of the structured control flow constructs of selection ( if/then/else) and repet ...
conventions that enable use of the system without prior specific knowledge.
[
]
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
Automation describes a wide range of technologies that reduce human intervention in processes, mainly by predetermining decision criteria, subprocess relationships, and related actions, as well as embodying those predeterminations in machine ...
through self-contained knowledge representation
Knowledge representation (KR) aims to model information in a structured manner to formally represent it as knowledge in knowledge-based systems whereas knowledge representation and reasoning (KRR, KR&R, or KR²) also aims to understand, reason, and ...
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 ''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.
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
]
Examples
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)
Criticism
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.[
]
See also
* Autological word
* Code readability
* Comment (computer programming)
In computer programming, a comment is text embedded in source code that a translator (compiler or interpreter (computing), interpreter) ignores. Generally, a comment is an annotation intended to make the code easier for a programmer to understa ...
* Controlled natural language
Controlled natural languages (CNLs) are subsets of natural languages that are obtained by restricting the grammar and vocabulary in order to reduce or eliminate ambiguity and complexity. Traditionally, controlled languages fall into two major types ...
* Literate programming
* Natural language programming
References
Further reading
*
Computer programming
Software documentation
{{Compu-lang-stub