From: Rick DeNatale <rick.denatale@...>
Date: 2007-04-10T03:10:28+09:00
Subject: Comments on Comments (was Re: Getting to 100 (#119))

On 4/9/07, Phillip Gawlowski <cmdjackryan@googlemail.com> wrote:
> Marcel Ward wrote:

> > I'm definitely in favour of comments and readability.  I guess I was
> > just verbalising some inner thoughts and wondering how others try to
> > find the right balance.
>
> Well, if the code is readable and speaks for itself, comments can be
> omitted. Otherwise, the comments should explain what the code does, not
> what it should do.
>
> I.e.:
> #Opening a file
> f = File.open("foo")
>
> ^
> |
> is superfluous.
>
> #This does stuff to the passed argument bar
> def do_stuff(bar)
>    #doing stuff to bar
> end
> ^
> |
> Isn't superfluous, and aids debugging if the thing doesn't do what it
> should. And you know that it doesn't do what it is supposed to do,
> because your tests tell you that it doesn't.

Even here one needs to be careful.

As Gerry Weinberg brought out in his classic "The Psychology of
Computer Programming," comments can actually impede debugging.

If as you say the comments say what the code should be doing, there is
a tendency to debug the comments rather than the code, which can make
it harder to spot the problem.  Commentary should really be left to
things which explain the context of the code.  The code should indeed
speak for itself.

Weinberg even suggests a tool which strips comments from code as
useful for debugging.

Now in the interest of taking my own medicine, looking at the code I
posted to rubyquiz which started all this.  I see two ways where I
used comments.

1)  To explain the general approach of the agorithm.  It's not so much
explaining what the code should be doing as why the code is written
the way that it is.

 # yield each partitioning of the receiver into count partitions
 #
 # This is a recursive implementation using composition of the block
 # argument.
 #
 # The approach is to iteratively split the string into two parts,
 # an initial substring of increasing length, and the remainder.
 # For each initial substring we yield an array which is the concatenation
 # of the initial substring and the partitioning of the remainder of
 # the string  into count-1 partitions.
 def each_partition(count, &b)
   # if the count is 1 then the only partition is the entire string.
   if count == 1
     yield [self]
   else
     # Iterate over the initial substrings, the longest initial substring must
     # leave at least count-1 characters in the remaining string.
     (1..(size-(count-1))).each do |initial_size|
       self[initial_size..size].each_partition(count-1) {|remaining|
         b.call([self[0,initial_size]] + remaining)}
     end
   end
 end
end

2) To describe an API -

# print combinations of digits and operators which evaluate to a goal
#
# Arguments are supplied by a hash the keys are:
#
#  Main arguments
#    :goal - the number being sought, default is 100
#    :digits - a string of digits, default is "123456789"
#    :ops - an array of strings representing the operators to be inserted into
#           digits, default is %w[- - +]
#
#  Additional arguments
#    :verbose - unless false, print all attempts, default is false
#    :return_counts - unless false, return an array of value, count arrays for
#                     values with multiple solutions, used to find interesting
#                     inputs, default is false
def get_to(options={})

Normally I only write comments for the second case.  However in the
case of ruby-quiz submissions, I see it as an opportunity for a shared
learning experience, and a way to communicate my way of approaching
Ruby to a wide variety of folks in the audience, particularly to the
many newbies.

> But such a thing merits it's own thread, I'd say.
>

Which is why I started it.
-- 
Rick DeNatale

My blog on Ruby
http://talklikeaduck.denhaven2.com/