“Do not say a little in many words,
but a great deal in a few.”
—Pythagoras (582-497 BCE)
Use complete sentences, properly punctuated.
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 snark_list
=
{
...
};
Do not use comments as a crutch. If your identifiers need commenting, maybe you need to choose better ones. If your logic needs commenting, maybe you need to clean it up.
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.