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] 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^[2]
Minimize the effort required to maintain or extend legacy systems^[2]
Reduce the need for users and developers of a system to consult secondary documentation sources such as code comments or software manuals^[2]
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 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^[2]
consistency^[2]
scope of the application and system requirements

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)
{
    if (text == NULL)
        return 0;

    size_t  count = 0;

    while (*text != '\0')
    {
        if (is_alphabetic(*text))
            count++;
        text++;
    }

    return count;
}

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.^[3]

References

↑ Schach, Stephen R. (2011). Object-Oriented and Classical Software Engineering (8 ed.). McGraw-Hill Professional. pp. 505–507. ISBN 978-0-07337618-9. OCLC 477254661.
1 2 3 4 5 Paul, Matthias R. (2002-04-09). "Re: [fd-dev] ANNOUNCE: CuteMouse 2.0 alpha 1". freedos-dev. Archived from the original on 2020-03-24. Retrieved 2020-03-24. […] almost any numeric value in source code should be replaced by a corresponding symbol. This would greatly improve the self-explanatory aspect of source code and significantly ease maintenance of the code in the long run, as it would enable one to search for symbols to find relations between different excerpts of the code. […]
↑ Raskin, Jef (2005-03-18). "Comments Are More Important Than Code - The thorough use of internal documentation is one of the most-overlooked ways of improving software quality and speeding implementation". ACM Queue. Development. ACM, Inc. 3 (2). Archived from the original on 2020-03-24. Retrieved 2019-12-22.