Five categories of comments I currently use in Racket (refined over the
years, and still sometimes refined further):
1. Comments prefixed with "TODO:", for things that either I know have to
be done, or that I might want to consider later. I often prefix the
former as "TODO: !!!", for historical reasons. I think that TODO
comments are more important than it seems most people think they are.
The funny thing with "TODO" comments is that they often persist in the
code much longer than you'd think they would.
2. Comments worded imperatively to give a higher-level description of
what is being done in the following lines of imperative code. In an a
bit of code with complicated branching, I'll sometimes start each block
with an imperative comment with a summary of conditions that got us
there, including contrastive emphasis, such as "Foo is *not* a bar, but
baz *is* null, so frob with the X factor."
3. Comments prefixed with "Note:" to give an aside that explains why we
are doing something the way we are doing it. Use this means of
conveying the info when it feels better than conveying the same info as
rationale in an imperative comment.
4. Disable code. Usually these should be removed eventually, although
occasionally I keep them in because certain code needs its unit tests
commented-out because the code normally can't depend on the unit test
framework.
5. Markers, such as simply ";;" for separating parts of a big list of
"require" forms (e.g., "for-syntax" vs. standard libraries vs.
non-standard libraries vs. modules that are part of the same library),
and sometimes ";;EOF". These aren't all that useful, and they're often
kinda ugly, but I still sometimes find reason to do them.
The other day, I also used "TODO: !!!" all-caps comments as placeholders
for someone else, in some code for a client, who wanted me to make an
app, and then they would add in a few bits of code very specific to
something in which they were expert. Normally, I would put a
library/framework border there, but in this case, working on the same
code file and using placeholder comments made more sense. I don't
expect to do this very often, so I'm not giving this category a number.
Note that descriptive identifiers and keywords can go a long way towards
readable code that does not need hardly any comments. I have written
some code (for which audit-ability was especially important) that reads
as close to English pseudocode, and most comments would be superfluous.
Neil V.
____________________
Racket Users list:
http://lists.racket-lang.org/users
