Self-documenting code

From Wikipedia, the free encyclopedia
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:

  • 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 through self-contained knowledge representation

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 numberOfWordsInThisArticle 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.

See also[edit]

References[edit]

  1. ^ Schach, Stephen R. (2011). Object-Oriented and Classical Software Engineering (8th ed.). McGraw-Hill Professional. pp. 505–507. ISBN 9780073376189. OCLC 477254661.

External links[edit]