Comments on Comments (was Re: Getting to 100 (#119))

On 4/9/07, Phillip Gawlowski <cmdjackryan@xxxxxxxxxxxxxx> 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/

.

Relevant Pages

  • Re: [QUIZ] Getting to 100 (#119)
    ... The main problem was partitioning the string of digits in order to ... I did this with a recursive method on String ... # an initial substring of increasing length, ... #:verbose - unless false, print all attempts, default is false ...
    (comp.lang.ruby)
  • Re: Comments on Comments (was Re: Getting to 100 (#119))
    ... Computer Programming," comments can actually impede debugging. ... # yield each partitioning of the receiver into count partitions ... # an initial substring of increasing length, ... # the string into count-1 partitions. ...
    (comp.lang.ruby)
  • Re: Open File For Input Method Faster Than File System Object Stream?
    ... Much depends on exactly what you are doing, and the best method to advise would depend chiefly on whether you are interested in only the first occurrence of the substring in the file or whether you want to check every line of the file for that substring. ... Dim s1 As String, fn As Long ... You could then use Instr in a loop to run through the entire string just once, searching for and recording (in an array of Longs) the position of every linefeed character it finds. ...
    (microsoft.public.vb.general.discussion)
  • Re: How to chck for string in array elements
    ... thends to get quite large, I want to optimize my algorithm som that if ... $string is a part of a element already stored in @words it won't be ... a substring of an element in the array. ...
    (comp.lang.perl.misc)
  • Re: How to chck for string in array elements
    ... thends to get quite large, I want to optimize my algorithm som that if ... But I cant figure out an efficient way to check if $string is ... a substring of an element in the array. ...
    (comp.lang.perl.misc)