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 ARBITRARYRoutine, variable and pointer namesas 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;
    }
   }

Copyright © 1981-2025 by The Computer Language Company Inc. All Rights reserved. THIS DEFINITION IS FOR PERSONAL USE ONLY. All other reproduction is strictly prohibited without permission from the publisher.