> > 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 <r...@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.mcb...@gmail.com> > *To:* Ben Duan <yfe...@gmail.com> > *Cc:* users <users@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 <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
