Self Documenting Code

1. Documentation

It contained inside the code itself. It consists of


Good Layout includes use of white space and effective use of spacing to make it easy to see the repetitions statements and selection statements of the program.


Require effective names. Names that say what the routines do. Make sure that they are used for only one purpose. For example Find, List, and Delete.


Also require effective names: They should describe what the constant is used for. Use constants instead of “magic” numbers.
Ex Define Ten = 10;


Make sure that variable names distinguish global, local, enumerated types, and constants. They should also like routines only do one task or be used for just one function. Don’t have “garbage” or “DoStuff” or “FooballRules” variable names.

Selection Statements:

Should have the normal case follow the IF expression instead of the else. Try to avoid as much as possible nested if statements. Try to make them read like English sentences. For example:

Control Statements:

Try to make them simple and have the loop control variables more descriptive then x, y or z. For example:

Like Selection Statements you should try to keep nesting of loop to a minimum.

Following these standards should naturally minimize the amount of comments that you have to implement. The necessity of comments is a hotly debated topic but it is widely accepted that they should be used in a number of levels. They can be stored as separate files describing what particular routines or modules do. They should also be inside the code. This is the lowest level that comments exist. They should be reserved for the tricky parts of your code and keep to a minimal because too much comments takes away from the readability of your code. While at the begging of each of your files you should include the PDL of your code.

Here are examples of bad and good routines.


Keys to Effective Comments

1.Should we use comments?

If we don’t do it well, it wastes your time and it wastes the time of anyone who tries to understand your code. But if its done well it makes the program a lot of easier to understand.

2.Commenting Efficiently

Effective commenting isn’t that time-consuming. Comments can take a lot of time to write for two common reasons. First, the commenting style might be time-consuming or tedious-a pain in the neck. Second, commenting might be difficult because the words to describe what the program is doing don’t come easily. The time you spend “commenting” is really time spent understanding the program better, which is time that needs to be spend regardless of whether you comment

Commenting Techniques

Good Comments should say things about the code that the code can’t say about itself. Good code is its own best documentation. Commenting is amenable to several different techniques depending on the level to which the comments apply: program, file, routine, paragraph, or individual

General good commenting technique

Things that should be documented in comments

Author: Brien Beattie, Dean Vargo, Yixiang Wang, Yawen Wu, Hong Zhang
Date : June 19, 2000.
Copyright: Department of Computer Science, University of Regina.

[CS Dept Home Page]