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

>
> 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.


Precisely


On Tue, Jul 9, 2013 at 11:56 AM, Rüdiger Asche <rac at ruediger-asche.de>wrote:

> **
> 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 <sean.mcbeth at gmail.com>
> *To:* Ben Duan <yfefyf at gmail.com>
> *Cc:* users <users at racket-lang.org>
> *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 <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
>>
>>
>  ------------------------------
>
> ____________________
>   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/20130709/739463fa/attachment.html>