Product Code Database
Example Keywords: socks -grand $76
barcode-scavenger
   » » Wiki: Self-documenting Code
Tag Wiki 'Self-documenting Code'.
Tag

In computer programming, self-documenting (or self-describing) and follow naming conventions and structured programming conventions that enable use of the system without prior specific knowledge. In , 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.


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 such as code comments or
  • Facilitate 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 article.numberOfWords 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
Below is a very simple example of self-documenting code, using naming conventions in place of explicit comments to make the logic of the code more obvious to human readers.

size_t count_alphabetic_chars(const char *text) {

   if (text == NULL)
       return 0;
     

   size_t  count = 0;
     

   while (*text != '\0')
   {
       if (is_alphabetic(*text))
           count++;
       text++;
   }
     

   return count;
     
}


Criticism
criticized the belief in "self-documenting" code by saying that code cannot explain the rationale behind why the program is being written or why it is implemented in such a way.


See also


Further reading
Page 1 of 1
1
Page 1 of 1
1

Account

Social:
Pages:  ..   .. 
Items:  .. 

Navigation

General: Atom Feed Atom Feed  .. 
Help:  ..   .. 
Category:  ..   .. 
Media:  ..   .. 
Posts:  ..   ..   .. 

Statistics

Page:  .. 
Summary:  .. 
1 Tags
10/10 Page Rank
5 Page Refs
1s Time