[ruby-talk:14024] Re: From Guido, with love...

#
# >> >  You don't need comment when  the code is very well written.
# >
# >    I don't think that could be further from the truth... Code
# that is well
# >written can still be extremely complex and hard for anyone to
# understand..
#
# There may be cases where well-written code is "extremely complex and
# hard for anyone to understand", but they are in my experience very
# few. I can't think one one example, actually.
#
# One of the primary purposes of source code is to communicate with
# other people, including future versions of ourselves.
#
# If some code seems to need comments, I work to improve the clarity and
# simplicity of the code. When I can't make the code any more clear and
# simple, if it still seems to need comments, I'll add them.
#
# It might be interesting to take some Ruby code here and see if we can
# make it not need comments.

OK, my two cents on commenting:

1. Comments like "this checks to see if myVar is NULL" are useless, and to
be avoided.

2. Comments that describe the nature and purpose of the algorithm to
follow -- no matter how readable the code itself might be -- help
tremendously, especially if they explain (for instance) why the following
algorithm was chosen over other possible considered alternatives. The notion
that just reading code because its so readable and the language itself is so
awesome that it will instantly clarify all questions is, well, kind of
naive, it seems to me.

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...). Nothing infuriates
me more as a lead developer than when a developer under me thinks
"everybody" should understand what he's trying to do, and doesn't bother to
offer comments to guide in the illumination process. Well, besides the
developer not getting the code done in the first place... ;)

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.

Sincerely,

Bob Calco