well, even though this side tracks the discussion even more, I can't help but
pitching in a few comments from a practitioner's point of view (I'm sure entire
seminars in college are dedicated to the topic of commenting, so this may or
may not be an old hat - apologies to anybody who may already have spent nights
debating those issues):
There are at least two levels to commenting, as you point out - one could
comment a line such as i = i+1 as "increment i" (useless) or, as "make sure i
is updated the next time around." (this second comment roughly corresponds to
your "only useful type of comments" below). Corresponding to lingulingo, I'd
like to tag these as "syntactic comments" and "semantic comments," respectively.
There are more levels, though. I don't consider the second example as
particularly useful unless the meaning of the code doesn't reveal itself with
medium effort - I expect every reasonably experienced developer to decipher
"what a piece of code does" by analyzing the code. If comments can help here,
fine.
But there is also pragmatics (to stay with lingulingo). Take a statement such
as i = 0. This obviously clears variable i, but frequently it's not only useful
to know *why* the variable needs to be cleared (possibly because some other
code makes assumptions about its value and only reuses the variable when it is
clear) but also why it is cleared *here* - in a typical real life scenario,
clearing it a few lines below or above may incur side effects, and frequently,
the moving of a given statement from one place to the other from version 1.x to
1.y is an indicator that in 1.x the place was wrong and has been corrected in
1.y (which is why version control tools are frequently much more helpful in
understanding code than comments).
Thus, I'd consider the following type of comment the most useful:
aReader->itsBadge = 0; // don't clear the badge# in the calling function foo
because bar also calls this function, so once we're done with the badge, we're
always clean.
// We must clear the member because
otherwise the next card may be read without a badge but leave this leftover
value which is a security breach.
Anything "below" this level of commenting to me generally is a reason to give
the person who wrote the comment a swift kick in the butt. He/she not only
distracts attention by making something (redundantly) explicit which is already
part of the code but also does not help the reader with something that really
needs to be remarked. I'd rather see no comment at all than a stupid comment.
Thus, there is nothing wrong per se with weakly commented code as long as there
are no pragmatics to be conveyed via comments.
Thanks for reading!
----- Original Message -----
From: Sean McBeth
To: Ben Duan
Cc: users
Sent: Tuesday, July 09, 2013 4:05 AM
Subject: Re: [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 <yfe...@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
------------------------------------------------------------------------------
____________________
Racket Users list:
http://lists.racket-lang.org/users
____________________
Racket Users list:
http://lists.racket-lang.org/users
