Internal Documentation

Internal documentation (ID) is a set of non-executable human-readable comments inserted into programming source code to make it easier to understand. Such comments are ignored by the compiler.

ID serves to explain the purpose of a piece of code, identify its author, record its date of modification or version number, explain its operation, justify its existence, suggest future developments etc. Good comments don't repeat the code or explain it. They clarify its intent.

Don't document the bleedin' obvious, e.g. String s = "Wikipedia"; /* Assigns the value "Wikipedia" to the variable s. */

Such documentation helps noone.

ID is useful enough for solo programmers to remind them of what they were thinking when they created the code months or years ago.

ID is especially vital for programming teams who often work on other team members' code and don't want to have to reverse-engineer some foreign code to work out what it does and how.

There is also external documentation which is kept in a separate document. ID has the advantage that can't be lost, and it's immediately accessible when the code is edited.

ID may be longer than the code it is in, but it does not increase the size of a compiled program: all the ID is ignored during compilation.

Tags

Certain tags are used in comments to assist in indexing common issues. Such tags are commonly syntax-highlighted and can be searched with common programming tools, such as the Unix grep utility. Examples of tag conventions include:

• FIXME to mark potential problematic code that requires special attention and/or review.
• NOTE to document inner workings of code and indicate potential pitfalls.
• TODO to indicate planned enhancements.
• XXX to warn other programmers of problematic or misguiding code.

To prevent obsolete tags accumulating over time, it is best to include the date and the tag author's name in the tag comment to ease tracking.

Sample ID

/* * Check if we are over our maximum process limit, but be sure to
* exclude root. This is needed to make it possible for login and
* friends to set the per-user process limit to something lower
* than the amount of processes root is running. -- Rik
*/
if (atomic_read(&p->user->processes) >= p->rlim[RLIMIT_NPROC].rlim_cur && !capable(CAP_SYS_ADMIN) && !capable(CAP_SYS_RESOURCE)) goto bad_fork_free;

10 REM This BASIC program shows the use of the PRINT AND GOTO statements.
15 REM It fills the SCREEN with the word "WIKIPEDIA"
20 PRINT "WIKIPEDIA"
30 GOTO 20

Commonly found in ID...

• Module name
• Author's name
• Date last modified
• Dependencies
• Description of the intent of the module
• Known bugs/problems
• Future work to be done