Self-documenting

In computer programming, self-documenting (or self-describing) is a common descriptor for source code that follows 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.cite book
first = Stephen R.
last = Schach
title = Object-Oriented and Classical Software Engineering
publisher = McGraw-Hill Professional
year = 2004
id = ISBN 0072865512] cite web
title = The Myth of Self-Describing XML
url = http://www.oceaninformatics.biz/publications/e2.pdf
accessdate = 2007-05-12] [(See e.g., Use-mention distinction, Naming collision, Polysemy)]

Overview

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.

The designation of "self-documenting code" is often applied in a general sense, and not thoroughly defined according to a rigorous and exacting standard. Nevertheless, there are certain objectives, conventions, and practical considerations that usually apply when users of a system refer to this concept.

Objectives

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

Self-documenting code is ostensibly written using human-readable names, typically consisting of a phrase in English 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

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
* consistency
* scope of the application and system requirements

Examples

An example of self-documenting software is TeX. When running on its own source code, TeX can produce a file with the complete printable documentation of itself.

Notes and references

ee also

* Literate Programming
* Comment

External links

* Jef Raskin on Self-documenting code: http://acmqueue.com/modules.php?name=Content&pa=showpage&pid=290&page=1.
* Steve McConnell's [http://cc2e.com/Page.aspx?hid=218 High Quality Routines checklist] in his book Code Complete helps to facilitate the creation of self-documenting code.