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

With respect to writing prose there's a saying, "Don't write to be
understood; write so that you can't possibly be misunderstood."

Which is the goal of writing code, where you have to explain _exactly_
what you mean to the computer. Which is hard work. Hard enough that
there's a likely cognitive bias -- the code must be self-explanatory
since you spent so much time getting it right, especially if it came
out (you feel) rather elegantly. In that frame of mind, there's likely
to be some fatigue or irritation associated with going on to write
comments, when "obviously" it already "speaks for itself".

Writing code is relatively easier in one respect, because the
"audience" is small and well-defined: the computer/environment.  When
it comes to writing code, and comments, for other programmers, now the
audience becomes more diverse. What's the background and experience of
the other programmers? How much do you explain vs. assume?

One audience member to keep in mind is a future version of you. You,
coming back months or years later. It can be an interesting and
education experience to discover how understandable your own code --
and the comments -- are.

Personally, I think the amount and type of comments varies by
programming language and style. In heavily OO C++ I found the class
design plus good names tended to make things more self-documenting;
maybe with some strategy hint like "// this is the Observer pattern".
In Java, the language itself is fairly verbose and sometimes feels
like "comments by other means". :)  Whereas in non-OO C, or in Racket,
it might be that documenting the key data structures heavily is the
sweet spot -- if that's clear, then the code manipulating them doesn't
need so many blow-by-blow comments. Maybe just the occassional
explanation of something like approximating 1/√x using 0x5f3759df. [1]

Browsing Racket's source code, I've often wished for just a _few_ more
comments. Especially a paragraph at the top of a module or complicated
function, giving some hint why it exists, what's generally going on.
However, I guess the deeper issue is that older parts of Racket use
older idioms -- more Scheme-influenced, and/or the way you had to code
it before Racket got X (and/or the way you still have to code it
because that portion of Racket can't require X).


[1] http://blog.quenta.org/2012/09/0x5f3759df.html