From: Dennis Decker Jensen <dennisdecker@...>
Date: 2001-04-23T00:14:58+09:00
Subject: [ruby-talk:14026] Comments in code (was Re: From Guido, with love...)

Bob Calco wrote:

<snipped two good points>

| The whole "I'm so cool, and Ruby is so readable, that I remove
| comments from
| any code before I try to read it" amount to so much hot air (no offense to
| whoever said it a few links back in the email chain...).
<snip>
| The fact is comments are a form of communication between one developer
| (writing the code) and another (reading the code), and communication is
| good. In some cases, they are one and the same person, separated
| by time. I
| have never regretted commenting my own code, though I have
| gnashed my teeth
| on occasion when I had to figure out the problem I had solved
| from scratch,
| and rediscover why it worked so well. A good habit of writing helpful
| comments is a necessary skill in a developer, I don't care how "readable"
| evangelists of a particular language (be it python or ruby or whatever)
| claim it is.

Good point about communication.

However, I don't see how it would be wrong to make your code so readable,
that you could get rid of all comments in it. Like you said: "Communication
is good."

�A lot has been said about the benefits of comments, and little
or nothing about their cost.  But they do have a cost.  Good
code, like good prose, comes from constant rewriting.  To
evolve, code must be malleable and compact.  Interlinear
comments make programs stiff and diffuse, and so inhibit the
evolution of what they describe.�
 - Graham, from "ANSI Common Lisp"

Regarding implementation language: I think I would need a lot more "helpful
comments" if I were to code in Forth or Assembler... :-)

That's why I like not only Ruby but many other high-level languages. They
are very helpful themselves...

--
Dennis Decker Jensen

�Never underestimate the power of details to utterly ruin a design.�
 - Robert C. Martin