Self-documenting

From Wikipedia, the free encyclopedia
Jump to: navigation, search

In computer programming, self-documenting (or self-describing) is a common descriptor for source code and user interfaces that follow certain loosely defined conventions for naming and structure. These conventions are intended to enable developers, users, and maintainers of a system to use it effectively without requiring previous knowledge of its specification, design, or behavior.[1][2][3]

Overview[edit]

The concept of self-description is not exclusively a property of certain kinds of source code. This concept has application to several areas in computer science, notably in computational linguistics and formal language theory. Additionally, self-describing systems may involve other areas in computing such as application design and user interfaces. Nevertheless, "self-documenting" is a term commonly used to designate a particular style of writing applied to source code for programming languages, markup languages, and the like.

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; and
  • 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. (2004). Object-Oriented and Classical Software Engineering. McGraw-Hill Professional. ISBN 0-07-286551-2. 
  2. ^ "The Myth of Self-Describing XML". Retrieved 2009-06-02. 
  3. ^ (See e.g., Use–mention distinction, Naming collision, Polysemy)

External links[edit]