Self-documenting code

From Wikipedia, the free encyclopedia
  (Redirected from Self-documenting)
Jump to navigation Jump to search

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.[citation needed]

Objectives[edit]

Commonly stated objectives for self-documenting systems include:

Conventions[edit]

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[edit]

There are certain practical considerations that influence whether and how well the objectives for a self-documenting system can be realized.

Examples[edit]

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[edit]

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

See also[edit]

References[edit]

  1. ^ 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.
  2. ^ a b c d e 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. […]
  3. ^ 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. [1][2]

Further reading[edit]