<div dir="ltr"><blockquote style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex" class="gmail_quote"><font face="Arial">Anything &quot;below&quot; 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&#39;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.</font></blockquote><div><br></div><div>Precisely <br></div></div><div class="gmail_extra"><br><br><div class="gmail_quote">On Tue, Jul 9, 2013 at 11:56 AM, Rüdiger Asche <span dir="ltr">&lt;<a href="mailto:rac@ruediger-asche.de" target="_blank">rac@ruediger-asche.de</a>&gt;</span> wrote:<br>

<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><u></u>





<div bgcolor="#ffffff">
<div><font face="Arial">well, even though this side tracks the discussion 
even more, I can&#39;t help but pitching in a few comments from a practitioner&#39;s 
point of view (I&#39;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):</font></div>
<div><font face="Arial"></font> </div>
<div><font face="Arial">There are at least two levels to commenting, as you 
point out - one could comment a line such as i = i+1 as &quot;increment i&quot; (useless) 
or, as &quot;make sure i is updated the next time around.&quot; (this second comment 
roughly corresponds to your &quot;only useful type of comments&quot; below). Corresponding 
to lingulingo, I&#39;d like to tag these as &quot;syntactic comments&quot; and &quot;semantic 
comments,&quot; respectively.</font></div>
<div><font face="Arial"></font> </div>
<div><font face="Arial">There are more levels, though. I don&#39;t consider the 
second example as particularly useful unless the meaning of the code doesn&#39;t 
reveal itself with medium effort - I expect every reasonably experienced 
developer to decipher &quot;what a piece of code does&quot; by analyzing the code. If 
comments can help here, fine.</font></div>
<div><font face="Arial"></font> </div>
<div><font face="Arial">But there is also pragmatics (to stay with 
lingulingo). Take a statement such as i = 0. This obviously clears variable i, 
but frequently it&#39;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).</font></div>
<div><font face="Arial"></font> </div>
<div><font face="Arial">Thus, I&#39;d consider the following type of comment 
the most useful:</font></div>
<div><font face="Arial"></font> </div>
<div><font face="Arial">aReader-&gt;itsBadge = 0;   // don&#39;t 
clear the badge# in the calling function foo because bar also calls this 
function, so once we&#39;re done with the badge, we&#39;re always clean.</font></div>
<div><font face="Arial">                                     // 
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.</font></div>
<div><font face="Arial"></font> </div>
<div><font face="Arial">Anything &quot;below&quot; 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&#39;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.</font></div>
<div><font face="Arial"></font> </div>
<div><font face="Arial">Thanks for reading!</font></div>
<div><font face="Arial"></font> </div>
<blockquote style="BORDER-LEFT:#000000 2px solid;PADDING-LEFT:5px;PADDING-RIGHT:0px;MARGIN-LEFT:5px;MARGIN-RIGHT:0px"><div><div class="h5">
  <div style="FONT:10pt arial">----- Original Message ----- </div>
  <div style="FONT:10pt arial;BACKGROUND:#e4e4e4"><b>From:</b> 
  <a title="sean.mcbeth@gmail.com" href="mailto:sean.mcbeth@gmail.com" target="_blank">Sean 
  McBeth</a> </div>
  <div style="FONT:10pt arial"><b>To:</b> <a title="yfefyf@gmail.com" href="mailto:yfefyf@gmail.com" target="_blank">Ben Duan</a> </div>
  <div style="FONT:10pt arial"><b>Cc:</b> <a title="users@racket-lang.org" href="mailto:users@racket-lang.org" target="_blank">users</a> </div>
  <div style="FONT:10pt arial"><b>Sent:</b> Tuesday, July 09, 2013 4:05 
AM</div>
  <div style="FONT:10pt arial"><b>Subject:</b> Re: [racket]Why experienced 
  programmers don’t use comments?</div>
  <div><font face="Arial"></font><font face="Arial"></font><br></div>
  <div dir="ltr">
  <div>Most comments are either redundant or a lie. When code changes, it&#39;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&#39;t match the code they reference, sometimes 
  in very subtle ways. <br><br>There is the added problem that most people don&#39;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.<br><br>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&#39;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. <br><br>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 &quot;take a guess -&gt; run the code -&gt; see the result -&gt; repeat 
  until expected results found&quot;. 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&#39;t understand but know throwing in a &quot;subtract one&quot; that a 
  buddy of theirs showed them in college fixes.<br><br></div>
  <div>There is actually one more type of comment that you&#39;re more likely to see 
  than actual, honest to goodness, useful comments. You&#39;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 &quot;just in case&quot; 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.<br></div>
  <div><font face="Arial"></font><font face="Arial"></font><br></div>
  <div>So that is why you don&#39;t see comments. Most of the types of comments that 
  you&#39;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.<br></div></div>
  <div class="gmail_extra"><font face="Arial"></font><font face="Arial"></font><br><br>
  <div class="gmail_quote">On Mon, Jul 8, 2013 at 9:41 PM, Ben Duan <span dir="ltr">&lt;<a href="mailto:yfefyf@gmail.com" target="_blank">yfefyf@gmail.com</a>&gt;</span> wrote:<br>
  <blockquote style="BORDER-LEFT:#ccc 1px solid;MARGIN:0px 0px 0px 0.8ex;PADDING-LEFT:1ex" class="gmail_quote">
    <div dir="ltr">Dear All,<br><br>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?<br><br>Thanks,<br>Ben</div><br>____________________<br>  Racket 
    Users list:<br>  <a href="http://lists.racket-lang.org/users" target="_blank">http://lists.racket-lang.org/users</a><br><br></blockquote></div><br></div>
  </div></div><p>
  </p><hr><div class="im">

  <p></p>____________________<br>  Racket Users list:<br>  
  <a href="http://lists.racket-lang.org/users" target="_blank">http://lists.racket-lang.org/users</a><br></div><p></p></blockquote></div>
</blockquote></div><br></div>