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

On Mon, Jul 08, 2013 at 10:05:57PM -0400, Sean McBeth wrote:
> 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.

Comments are necessary when there is a significant intellectual gap 
between the code as written and the intended meaning.  Granted, this 
gap has been reduced by the development of high-level languages, but 
comments are still often necessary.  Mismatch between comment and code 
is a bug that needs to be fixed.

I find that often the only way I can understand a large chunk of code 
written by others is to comment it.  Granted, most of these comments 
are tentative, of the form, "Could this function be inverting an upper 
triangular matrix?" or "It looks as i + j > c - k."  Eventually these 
comments become more definite, and finally the strructure of the code 
is clear.
  
> 
> 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.

When you're a beginner that has never seen an assignment statement 
before, it's useful to be told that
	i := i + 1
increments the value found in the variable i.  THis isn't useful for an 
experienced programmer.  But the programming textbooks are aimed 
precisely at beginners, so they use the kind of comments that their 
target audience needs.

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

This is true; obvious is good.  But it's sometimes hard to achieve, 
especially if there is a huge conceptual gap between the operations and 
libraries available in the programming language and the task to be 
accomplished by the program.  Proper choices of names for data 
structures and functions helps, but may not be enough.  When you get to 
languages with explicitly presented interfaces, you can't even tell 
from the interface definition what the code that emolements is doing.  
Comments are essential to document interfaces.

> 
> The only useful type of comments are those that document *why* the code
> does what it does.

Kind of like documenting the purpose of the code.

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

Which situation is ameliorated by using explicit invariants for loops, 
and including them in the comments.  They're useful signposts when 
coding and debugging.  Some of these invariants might even be 
executable enough that it's proactical to put them in assert 
statements; others not.

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

Commenting code out is very useful as a transitional measure when 
cleaning code up.  You see the old code and the new code side-by-side, 
and can check that the two do the same thing.  But it's only a 
transitional measure, and should disappear when the new code is 
completed, debugged, and tested.

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

Thanks for this last sentence.  Until now your post seemed to be a rant 
against internal documentation.  But this provides clear reasons 
why practical considerations often lead to neglect of good practice, 
other than the common case of incompetence.

-- hendrik

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