From: "Benjamin J. Tilly" <ben_tilly@...>
Date: 2001-04-24T01:49:16+09:00
Subject: [ruby-talk:14088] Re: From Guido, with love...

Ron Jeffries wrote:
>On Sun, 22 Apr 2001 04:38:04 +0900, "Mitch Vincent" <mitch@venux.net>
>wrote:
>
>>> >  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.

What problem space are you working in, and what problem space
is your audience from?  The example that immediately comes to
my mind is an implementation of an unfamiliar mathematical
algorithm.  Unless you have lot of math you are simply not
going to understand what an efficient factoring algorithm is
doing.  (In fact this is true even if you do have a lot of
math if you have not been working in number theory recently.)

In that case a simple comment documenting which algorithm you
are using and pointing at a sample reference would greatly
clarify how your code works, and what it is supposed to be
doing.

>One of the primary purposes of source code is to communicate with
>other people, including future versions of ourselves.

And when the code relies on a large amount of domain specific
information that I am not going to retain, I add them.  Or
when it is meant to be read by people who don't have domain
specific information that I do, comments are justified to
understand what the code does.  Strictly speaking these are
not comments about what the code does, but rather about what
you need to know to figure that out...

In addition in Perl, I like to comment public functions with
a short note on what the arguments in and out are.  In Ruby
the declaration for the function seems to serve that purpose.
However if I am writing something for public use, I believe
that it is both important and valuable (even in Ruby) to have
those usage comments.  Users should not need to understand my
code to use it.  (They should be able to understand my code
as well, but it should not be a requirement.)

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

As someone who goes by the nickname I0 on PerlMonks once put
it, "I find the most useful comments state what remains
invariant, while the code states what gets transformed."

I have found that a very valuable comment.

Details of how the code works almost never are worth putting
comments on.  Public interfaces always deserve them.  But
interfaces for things that are not public may or may not.
(Though I tend to put them in.)

Public is, of course, also a matter of perspective.  While a
medium project may be refactorable and "public" interfaces
changed, should Matz try to seriously refactor the public
interfaces of Ruby, I think we would all be upset.  (The code
behind the scenes could be refactored with much less
difficulty of course...)

>It might be interesting to take some Ruby code here and see if we can
>make it not need comments.

I doubt that would be hard.

It would also be unlikely to change the opinions that I just
stated.  (Which I suspect are very close to yours anyways.)

Cheers,
Ben