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

Most comments are either redundant or a lie. When code changes, it's easy
to forget to update the comments to the code. So over the course of a
project, you end up with comments that don't match the code they reference,
sometimes in very subtle ways.

There is the added problem that most people don't know how to comment
properly. Most people end up writing comments that describe what the code
is doing. Unfortunately, most instructive material demonstrates commenting
with this style of comments. This is why people forget to update the
comments when they change the code: redundancy is not something humans are
good at. In any project of meaningful size, the incidence of defects is
proportional to the volume of code, so reducing redundancy is a way to try
to reduce the amount of typing a programmer must do, and thus the
mean-time-to-writing-a-defect.

The code should be written in such a way that what it does is obvious. Code
is meant to be read by humans first, run on computer second. If it were
more important for the computer to run the code than the human to read the
code, we'd be writing raw machine language, not in compiled languages. So
if the code is not clear in what it does, then it is a defect of the
highest order.

The only useful type of comments are those that document *why* the code
does what it does. Why did a particular person write a particular function
using for/list instead of map, or vise versa? Unfortunately, people rarely
do this, because very, very few people understand why they are writing the
code they are writing. Most people code in a cycle of "take a guess -> run
the code -> see the result -> repeat until expected results found". To
them, there is no more meaning to a for loop that runs from 0 to
arrayLength minus one than from 0 to arrayLength, other than they have been
conditioned to know that the latter causes an error, an error that they
don't understand but know throwing in a "subtract one" that a buddy of
theirs showed them in college fixes.

There is actually one more type of comment that you're more likely to see
than actual, honest to goodness, useful comments. You're likely to see a
comment that removes a section of code from execution, perhaps even with a
not from the person who made the change explaining that they made it, when
they made it, and *maybe* why they made the change. This is also not
useful, because source control has a record of the change and who made it
on what date and time, and it is confusing to other programmers to see this
left over code, as it suggests an unknown flux in the code, it is unknown
if they are unfinished features or deprecated features. If the original
programmer left it in "just in case" it is needed again in the future, it
belies A) that he or she does not understand the system and its
requirements, B) does not have confidence in his or her own abilities to
recreate the missing feature without referring to the old code, C) does not
understand the current requirements to know that the old code will not be
needed, and D) does not know how to use source control properly so that, in
the exceedingly rare event it is needed, it is easily recoverable.

So that is why you don't see comments. Most of the types of comments that
you're likely to see are complete garbage. Good comments are hard to write,
the code is on a deadline, and the comment does not aid in execution in any
way. So, like unit tests, validation scripts, error handling, transaction
guards, etc., they get dropped on the floor in favor of the barest
interpretation of the requirements.


On Mon, Jul 8, 2013 at 9:41 PM, Ben Duan <yfefyf at gmail.com> wrote:

> Dear All,
>
> I have a question here. There’s an extensive use of comments in HtDP. But
> there are few comments in experienced programmers’ code, for example in
> racket’s source code. Why is that?
>
> Thanks,
> Ben
>
> ____________________
>   Racket Users list:
>   http://lists.racket-lang.org/users
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.racket-lang.org/users/archive/attachments/20130708/71e47f94/attachment.html>