📑 Table of Contents▼

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]

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

    size_t  count = 0;

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

    return count;
}

Criticism

edit

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]

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. 3 (2). ACM, Inc. Archived from the original on 2020-03-24. Retrieved 2019-12-22. [1][2]

Further reading

edit


Stub icon

This programming-language-related article is a stub. You can help Wikipedia by adding missing information.

📚 Artikel Terkait di Wikipedia

Self-modifying code

In computer science, self-modifying code (SMC or SMoC) is code that alters its own instructions while it is executing – usually to reduce the instruction

Assembly language

can reference those locations by name, thus promoting self-documenting code. In executable code, the name of each subroutine is associated with its entry

Human-readable medium and data

type in. Self-documenting code – source code that is both machine-readable and human-readable Human-readable code Machine-Readable Documents Machine-readable

Rule of three (C++ programming)

one, then an explicit definition, although redundant, will be "self-documenting code" indicating that it was an intention rather than an oversight. Modern

Constant (computer programming)

programmers and compilers: for programmers, they are a form of self-documenting code and allow reasoning about correctness, while for compilers, they

Literate programming

dynamic statistical reports Self-documenting code – source code that can be easily understood without documentation Vibe coding v w x y z Knuth, Donald E

Comparison of documentation generators

formats the generators can write. Code readability Documentation generator Literate programming Self-documenting code Ddoc has a macro system which can

HyperTalk

operator used a natural language syntax making for easily readable, self-documenting code. For instance, a script stored in a button on a card might wish