[racket] Why experienced programmers don’t use comments?

From: Neil Van Dyke (neil at neilvandyke.org)
Date: Tue Jul 9 12:34:45 EDT 2013

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 

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.

Posted on the users mailing list.