Self-documenting code: Difference between revisions
m +category |
|||
| Line 17: | Line 17: | ||
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. |
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. |
||
"Self-documenting code" is a falacy... you will forget what you did and others will not understand what you did or why - USE COMMENTS LIBERALLY! |
|||
===Objectives=== |
===Objectives=== |
||
Revision as of 22:25, 28 March 2012
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.[1][2][3]
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.
"Self-documenting code" is a falacy... you will forget what you did and others will not understand what you did or why - USE COMMENTS LIBERALLY!
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 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
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
See also
References
- ^ Schach, Stephen R. (2004). Object-Oriented and Classical Software Engineering. McGraw-Hill Professional. ISBN 0072865512.
- ^ "The Myth of Self-Describing XML" (PDF). Retrieved 2009-06-02.
- ^ (See e.g., Use–mention distinction, Naming collision, Polysemy)
External links
- Jef Raskin on Self-documenting code: http://acmqueue.com/modules.php?name=Content&pa=showpage&pid=290&page=1.
- Steve McConnell's High Quality Routines checklist in his book Code Complete helps to facilitate the creation of self-documenting code.
 | This programming-language-related article is a stub. You can help Wikipedia by expanding it. |