From: Bob Calco <rcalco@...>
Date: 2001-04-23T01:04:23+09:00
Subject: [ruby-talk:14027] RE:  Comments in code (was Re: From Guido, with love...)

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

I'm not advocating *not* making code so readable it (theoretically)
shouldn't need a comment to explain it. And I agree that some languages
certainly do require more rigorous commenting to make any sense out of what
they are doing (assembler being something of an extreme example...).

And I agree that Ruby, Python, etc., minimize the need for blow-by-blow
comments to a great degree, much of what they are doing being "plainly
visible", and that's good -- a self commenting language syntax is certainly
something worth striving for in a language. However, one should not have to
read a whole section of code before they know what they are looking at,
particularly (and this is really the only point I want to emphasize) when
the developer is implementing a particular *algorithm* (in contradistinction
to other alternatives that might pop into the mind of the reader).

I cannot see how even the cleanest code eliminates doubt in the reader's
mind as to whether the original code author was thinking correctly when
he/she chose *that* particular way of getting the job done. Also, comments
that explain what requirement is being satisfied by the implementation to
follow help judge whether, in fact, the code maps cleanly to the
requirements. This is not something that can be expressed syntactically in
any language -- it takes a comment to make that case.

Finally, comments can be used by document generating utilities to create API
manuals, or just plain old HTML help explaining what each function and its
various implementation steps "do" (or are supposed to do) for new developers
to get up to speed on the code before they start mucking around in it.

Any way you look at it, ripping comments out before reading the code is a
really bad idea, IMHO. Even bad comments give you some clue as to the
developer's competence and capability levels -- something else I try to
gleen out of code reviews, to help move them along in the right direction.

As far as I'm concerned, the bad comments are worth tolerating for the sake
of the priceless gems that otherwise would never get put in the code because
of a naive reliance on the supposed "readability" of the underlying
language, and a moral conviction that every developer *should* write
perfectly readable code in that language.

As the great philosopher, Forrest Gump, said: "And that's all I have to say
about that."

;)

Sincerely,


Bob Calco

# -----Original Message-----
# From: Dennis Decker Jensen [mailto:dennisdecker@mail.tele.dk]
# Sent: Sunday, April 22, 2001 11:15 AM
# To: ruby-talk ML
# 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
#
#