Transcript Internal comment style

Internal Documentation
Conventions
Kinds of comments
• javadoc (“doc”) comments describe the
user interface:
– What the classes, interfaces, fields and methods
are for
– How to use them
• Obviously, the maintainer needs to know
what the code does
• In addition, the maintainer needs to
understand how the code works
Kinds of internal comments
• “Standard” (C-style) comments: /* ... */
• One-line and end-line comments:
// a one-line comment is on a line by itself
x = 0; // an end-line comment follows code
– These are both “internal” comments, seen only
by someone looking at your code
– Internal comments are only for maintainers
– But avoid things that would embarrass you to a
user!
Which kind of internal comment?
• Rule 36: Use “standard” (/*...*/) comments
to comment out code without removing it.
• I don’t agree
– Suggested because it’s usually easy to do, but...
– BlueJ’s comment and uncomment commands
make it easier to use one-line (//...) comments
– Standard comments cannot be nested, so it’s
tricky commenting out code with comments
• One-line comments don’t have this problem
Explaining the code I
• Rule 59: Add internal comments only if they will
aid in understanding your code.
• Don’t repeat the javadoc comments
• Don’t put in comments to explain things that are
obvious from the code
• Don’t put in irrelevant or useless comments
// Diamondbacks beat the Yankees, 3 - 2
• Always put comments before the code they
describe, never after the code
Explaining the code II
• Rule 37: Use one-line comments to explain
implementation details.
• One-line comments are also good for writing
reminders for yourself about things you still need
to work on
// need to rewrite this if more than one rabbit
• I like to use one-line comments to tell what the
next block of code is going to do
// put the rabbit in a random location
End-line comments I
• Rule 61: Avoid the use of end-line comments.
– This rule is largely to prevent overly long lines
– But: Rule 62: Explain local variable declarations
with an end-line comment.
int edgeDistance; // distance to the nearest edge
– And: Rule 64: Label closing braces in highly nested
control structures.
} // end switch
} // end if
} // end for j
} // end for i
End-line comments II
• I also find end-line comments useful for an
else that is a long way from its if:
if (distance > 5) {
a lot of code in between
}
else { // distance <= 5
...
}
Unresolved issues
• Rule 63: Establish and use a set of
keywords to flag unresolved issues.
– I personally like to use $$
• // $$ the canvas isn't being redrawn properly
– More specific flags are likely to be used in
large projects
Intentionally missing break
• Rule 65: Add a “fall-through” comment
between two case labels of a switch
statement, if no break statement separates
those labels.
– The switch statement is so badly designed that
forgetting the break is a common error
– To keep an intentionally missing break from
being “corrected,” add a comment
Label empty statements
• Sometimes you intentionally use a loop
with an empty statement body
• Rule 66: Label empty statements.
while ((c = reader.read()) == space) ;
// Empty body
• I prefer a different solution: use an empty
block as the statement body
while ((c = reader.read()) == space) { }
Don’t repeat the code
• Rule 60: Describe why the code is doing
what it does, not what the code is doing.
• Another way of saying this is:
Comments should not echo code.
– Here’s a typical example of a bad comment:
count = 0; // set count to zero
• You should assume that anyone reading
your internal comments knows some Java!
Use the active voice
• Rule 34: Use the active voice, and omit
needless words
– // zero out the array
– // each of the elements of the array is set to
// zero by the following loop
• Writing comments is still writing--all the
rules for good writing apply to comments
• Best reference: The Elements of Style, by
Strunk and White
Debugging statements
• We sometimes put in debugging statements
that we plan to remove afterwards
• Simple trick: start these “temporary”
statements in the first column, so you can
find them easily
boolean legalLocation(int row, int col) {
System.out.println("legalLoc " + row + " " + col);
return row >= 0 && row < numRows &&
column >= 0 && column < numCols;
}
The End