Re: Comments on Comments (was Re: Getting to 100 (#119))
- From: Phillip Gawlowski <cmdjackryan@xxxxxxxxxxxxxx>
- Date: Tue, 10 Apr 2007 10:31:08 +0900
Rick DeNatale wrote:
On 4/9/07, Phillip Gawlowski <cmdjackryan@xxxxxxxxxxxxxx> wrote:
#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.
I guess that is what I meant. Comments should be an aid, if one comes back to the code after a few months or years, to understand what one's intentions where when writing a particular piece of code, especially if it wasn't in the "expected" or canonical way how things usually are done. And of course, the code should speak for itself, and, as I've noticed, in Ruby it usually does. When it doesn't, it is because of a lack of understanding on *my* part, not because the source code is obscure.
Weinberg even suggests a tool which strips comments from code as
useful for debugging.
In the context, that almost all comments are either vanity comments, or are of the superfluous kind (especially in statically typed languages, it is not needed to add a comment what type of variable is declared), this will be useful.
I can only speak form a hypothetical point of view, as I didn't yet use more debugging tools than ruby -w foo.rb.
But that is changing.
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
That is a good example of the kind of comment I meant, as well as the second of your examples. The example above allows for a better interpretation of things, as it states the intention of the source code, as well as describing what it *should* be doing, rather than what it does. In an ideal world, both are identical, but in the real world, bugs and OS inconsistencies don't allow for the *should* and *does* to be in sync.
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.
In this example, the comments are documentation. Great for something like RDoc, to process and output an API description, as well as making it easier if one has to look at the source code directly.
IMHO, it is only necessary to look into the source in two cases:
1) To learn.
2) To correct errors in the behavior.
--
Phillip "CynicalRyan" Gawlowski
http://cynicalryan.110mb.com/
Rule of Open-Source Programming #20:
Open Code != Good Code
.
- Follow-Ups:
- Re: Comments on Comments (was Re: Getting to 100 (#119))
- From: John Joyce
- Re: Comments on Comments (was Re: Getting to 100 (#119))
- References:
- Comments on Comments (was Re: Getting to 100 (#119))
- From: Rick DeNatale
- Comments on Comments (was Re: Getting to 100 (#119))
- Prev by Date: How to Write a Spelling Corrector
- Next by Date: Re: mysql install problems
- Previous by thread: Comments on Comments (was Re: Getting to 100 (#119))
- Next by thread: Re: Comments on Comments (was Re: Getting to 100 (#119))
- Index(es):
Relevant Pages
|
