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