Term of the Moment

lenticular 3D


Look Up Another Term


Redirected from: source code documentation

Definition: program documentation


Explaining in one's native language (English, Spanish, Russian, etc.) what the source code of a program does. Throughout the history of programming, the range of program documentation ranges from extremely thorough to non-existent, the latter causing immense problems later if the application must be changed.

The Problem Is Twofold
Every function, variable and constant a programmer writes from scratch must be given a name, and programmers can make up any name they desire. For example, instead of a "MakeUpperCase" function (routine), a programmer can write "makeUC," "upc" or "aj7kd6mk." It is entirely arbitrary. Obviously, the more descriptive the naming, the clearer the documentation. See function, variable and constant.

Secondly, explaining technical subjects is difficult, which is evident given how often people abhor reading manuals (see RTFM). As a result, even if the code is documented, it may be difficult to decipher.

Examine the Example Below
Following is a tiny snippet from a program written in C that converts the source text files of this encyclopedia into XML files. Notice how much is defined by the programmer. See self-documenting code, documentation and source code.

 *************************************
 SOURCE CODE LEGEND IN THIS EXAMPLE:

 1 - ENTIRELY ARBITRARY
 Routine, variable and pointer names
 as well as documentation.
 Made up by the programmer.

 2 - FIXED
 Instructions and symbols.
 Part of the language.
 *************************************


 StartDefinition:
  insCODE ("<definition>");
  ENDLINE(1); 
  if (ConvertNOTES) 
  insCODE ("<notes>");

 /* do BBB's follow notes code? */
  if (*INptr=='B') 
   BookBypass=YES;
   else BookBypass=NO;

  while (*INptr != '-')
  Bump(1);    /* locate first dash */
  while (*INptr == '-')
  Bump(1);    /* delete rest of dashes */

  /* process to 2nd notes code   */
  NotesLoc=0;
  while (*INptr != NOTESCODE)
{
   if (*INptr == BEGINXYCODE)
    {
    printERROR("<< found before 2nd Notes code.");
    return;
    }
   }