“Do not say a little in many words,
but a great deal in a few.”
—Pythagoras (582-497 BCE)
“Omit needless words! Omit needless words! Omit needless words!”
—Will Strunk
Commenting is a form of expository writing, and as such the rules of expository writing apply:
Briefer is better — but clarity beats brevity.
If you don’t already have a copy, buy and read Strunk and White’s Elements of Style. It is the best book on commenting available. Get the classic version they wrote, not the recent version mangled after their deaths without their permission nor taste.
Break comment lines at 40-50 characters — 72 maximum.
Write high-level comments motivating the package as well as low-level ones elucidating details.
Put a motivating comment before each major function. Use short imperative sentences:
# Boojum the snarks thrice each
# to re-establish the softly and
# silently vanishing invariants:
#
fun boojum_snarks snark_list
=
{
...
};
Do not use comments as a crutch. If you find yourself writing
bpl = []; # Breakpoint list.
it means you should rename bpl to breakpoint_list. (When cleaning up other people’s code I find that more often than not the comment where an identifier is declared contains the proper name of that identifier.)
Don’t be stupid. Comments like
close file; # Close file.
do not help anyone. Make every word count.
Do not needlessly break a sentence or clause across lines. For example, do not write
# Oh frabjous day, we have a boojum. Softly
# and silently steal it away.
but rather
# Oh frabjous day, we have a boojum.
# Softly and silently steal it away.