العربية
中国
Français
Deutsch
Ελληνική
हिन्दी
Italiano
日本語
Português
Русский
EspañolSELF-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.
[1]
[2]
[3]
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 throroughly 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.
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.
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.
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
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.
1. Object-Oriented and Classical Software Engineering, , Stephen R., Schach, McGraw-Hill Professional, 2004, ISBN 0072865512
2.
The Myth of Self-Describing XML
3. (See e.g., Use-mention distinction, Naming collision, Polysemy)
★ Literate Programming
★ Comment
★ 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.
[1]
[2]
[3]
| Contents |
| Overview |
| Objectives |
| Conventions |
| Practical considerations |
| Examples |
| Notes and references |
| See also |
| External links |
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 throroughly 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
1. Object-Oriented and Classical Software Engineering, , Stephen R., Schach, McGraw-Hill Professional, 2004, ISBN 0072865512
2.
The Myth of Self-Describing XML
3. (See e.g., Use-mention distinction, Naming collision, Polysemy)
See 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 High Quality Routines checklist in his book Code Complete helps to facilitate the creation of self-documenting code.
This article provided by Wikipedia. To edit the contents of this article, click here for original source.
psst.. try this: add to faves
