In
computer programming, self-documenting (or self-describing)
source code
In computing, source code, or simply code, is any collection of code, with or without comments, written using a human-readable programming language, usually as plain text. The source code of a program is specially designed to facilitate the w ...
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 fr ...
s follow
naming conventions
A naming convention is a convention (generally agreed scheme) for naming things. Conventions differ in their intents, which may include to:
* Allow useful information to be deduced from the names based on regularities. For instance, in Manhatta ...
and
structured programming
Structured programming is a programming paradigm aimed at improving the clarity, quality, and development time of a computer program by making extensive use of the structured control flow constructs of selection ( if/then/else) and repetition ( ...
conventions that enable use of the system without prior specific knowledge.
In
web development
Web development is the work involved in developing a website for the Internet (World Wide Web) or an intranet (a private network). Web development can range from developing a simple single static page of plain text to complex web applications, ...
, 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
Automation describes a wide range of technologies that reduce human intervention in processes, namely by predetermining decision criteria, subprocess relationships, and related actions, as well as embodying those predeterminations in machines ...
through self-contained
knowledge representation
Knowledge representation and reasoning (KRR, KR&R, KR²) is the field of artificial intelligence (AI) dedicated to representing information about the world in a form that a computer system can use to solve complex tasks such as diagnosing a medic ...
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
A naming convention is a convention (generally agreed scheme) for naming things. Conventions differ in their intents, which may include to:
* Allow useful information to be deduced from the names based on regularities. For instance, in Manhatta ...
* consistency
* scope of the application and
system requirements
To be used efficiently, all computer software needs certain hardware components or other software resources to be present on a computer. These prerequisites are known as (computer) system requirements and are often used as a guideline as opposed ...
Examples
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)
Criticism
Jef Raskin
Jef Raskin (born Jeff Raskin; March 9, 1943 – February 26, 2005) was an American human–computer interface expert best known for conceiving and starting the Macintosh project at Apple in the late 1970s.
Early life and education
Jef Raskin ...
criticizes 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
An autological word (also called homological word) is a word that expresses a property that it also possesses (e.g., "word" is a word, "noun" is a noun, "English" is an English word, " pentasyllabic" has five syllables, and "writable" is writab ...
*
Code readability
Computer programming is the process of performing a particular computation (or more generally, accomplishing a specific computing result), usually by designing and building an executable computer program. Programming involves tasks such as an ...
*
Comment (computer programming)
In computer programming, a comment is a programmer-readable explanation or ''annotation'' in the source code of a computer program. They are added with the purpose of making the source code easier for humans to understand, and are generally ign ...
*
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
Literate programming is a programming paradigm introduced in 1984 by Donald Knuth in which a computer program is given as an explanation of its logic in a natural language, such as English, interspersed (embedded) with snippets of macros and t ...
*
Natural language programming
Natural-language programming (NLP) is an ontology-assisted way of programming in terms of natural-language sentences, e.g. English. A structured document with Content, sections and subsections for explanations of sentences forms a NLP document ...
References
Further reading
*
Computer programming
Software documentation
{{Compu-lang-stub