Download SOEN 341 Software Process

SOEN 341/4 S
9.2.5
Winter 2000
79
Commenting Conventions
Comments are an essential part of a program but you should not over use them. The following
rule will help you to avoid comments:
Comments should not provide information that can be easily inferred from the code.
There are two ways of applying this rule.
• Use it to eliminate pointless comments:
counter++;
// Increment counter.
// Loop through all values of index.
for (index = 0; index < MAXINDEX; index++)
{ .... }
• Use it to improve existing code. When there is a comment in your code that is not
pointless, ask yourself “How can I change the code so that this comment becomes pointless?”
You can often improve variable declarations by applying this rule. Change
int np;
int flag;
int state;
double xcm;
double ycm;
//
//
//
//
//
Number of pixels counted.
1 if there is more input,
0 = closed, 1 = ajar, 2 =
X-coordinate of centre of
Y-coordinate of centre of
otherwise 0.
open.
mass.
mass.
to
int pixelCount;
bool moreInput;
enum { CLOSED, AJAR, OPEN } doorStatus;
Point massCentre;
There should usually be a comment of some kind at the following places:
• At the beginning of each file (header or implementation), there should be a comment
giving the project that the file belongs to and the purpose of this file.
• Each class declaration should have a comment explaining what the class is for. It is
often better to describe an instance rather than the class itself:
class ChessPiece
{
// An instance of this class is a chess piece that has a position,
// has a colour, and can move in a particular way.
....