Look Up Another Term

Definition: program documentation


Explaining in one's native language 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" or "upc" or "mkucase." Obviously, the more descriptive the naming, the clearer the documentation. See function, variable and constant.

Secondly, explaining technical subjects is very difficult, which is more than evident given how often people abhor reading user manuals (see RTFM). As a result, even if the code is documented, it may be difficult to decipher. Following is a tiny snippet from the program that converts the source text files of this encyclopedia into XML files. Written in C, all the names for routines, variables and pointers, as well as documentation are in boldface, all of which are arbitrary names created by the programmer. As is evident, the programmer makes up a lot of the names in a program. See self-documenting code, documentation and source code.


 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;
    }
   }