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

**URL:** <https://www.ruby-forum.com/t/comments-on-comments-was-re-getting-to-100-119/91494>\
**Category:** Ruby\
**Created:** [April 9, 2007, 8:11pm UTC](https://www.ruby-forum.com/t/comments-on-comments-was-re-getting-to-100-119/91494 "2007-04-09T20:11:28Z")\
**Posts on this page:** 5\
**Page:** 1

<div class="post-metadata">

**Author:** ![rykkers](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/r/e5b9ba/32.png) [@rykkers](https://www.ruby-forum.com/u/rykkers)\
**Post date:** [April 9, 2007, 8:11pm UTC](https://www.ruby-forum.com/t/comments-on-comments-was-re-getting-to-100-119/91494/1 "2007-04-09T20:11:28Z")

</div>

On 4/9/07, Phillip G. [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid) wrote:

> Marcel W. wrote:

> f = File.open(“foo”)  
> |  
> 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

1. 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/](http://talklikeaduck.denhaven2.com/)

---

<div class="post-metadata">

**Author:** ![rykkers](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/r/e5b9ba/32.png) [@rykkers](https://www.ruby-forum.com/u/rykkers)\
**Post date:** [April 10, 2007, 3:32am UTC](https://www.ruby-forum.com/t/comments-on-comments-was-re-getting-to-100-119/91494/2 "2007-04-10T03:32:17Z")

</div>

Rick DeNatale wrote:

> > because your tests tell you that it doesn’t.  
> > 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.

> # This is a recursive implementation using composition of the block
> 
> ```
> yield [self]
> 
> ```
> 
> 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.

> inserted into
> 
> 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/](http://cynicalryan.110mb.com/)

Rule of Open-Source Programming #20:

Open Code != Good Code

---

<div class="post-metadata">

**Author:** ![rykkers](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/r/e5b9ba/32.png) [@rykkers](https://www.ruby-forum.com/u/rykkers)\
**Post date:** [April 10, 2007, 6:00am UTC](https://www.ruby-forum.com/t/comments-on-comments-was-re-getting-to-100-119/91494/3 "2007-04-10T06:00:26Z")

</div>

The superfluous comments can be good, especially for learners, it can  
be like a tutorial or a book, but perhaps verbose comments should be  
included in a separate copy of the source. Then they can be read side  
by side. Of course that ends up being a version control pain in the  
butt too.  
Now, if Ruby had multi-line comments… code folding could take care  
of that.

---

<div class="post-metadata">

**Author:** ![rykkers](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/r/e5b9ba/32.png) [@rykkers](https://www.ruby-forum.com/u/rykkers)\
**Post date:** [April 10, 2007, 6:08am UTC](https://www.ruby-forum.com/t/comments-on-comments-was-re-getting-to-100-119/91494/4 "2007-04-10T06:08:26Z")

</div>

John J. wrote:

> The superfluous comments can be good, especially for learners, it can be  
> like a tutorial or a book, but perhaps verbose comments should be

In such a case, yes. But reading source alone is no substitute for a  
good book on the language, or you end up with an amount of source code,  
that is prohibitive. A language is a lot more than _just_ its keywords  
and stdlib, but includes a philosophy. And a book can split the process  
of learning into much more manageable chunks. YMMV, though.

> included in a separate copy of the source. Then they can be read side by  
> side. Of course that ends up being a version control pain in the butt too.  
> Now, if Ruby had multi-line comments… code folding could take care of  
> that.

=begin  
A  
multi-  
line  
comment  
=end

Add an rdoc behind the =begin, and it will be parsed by RDoc, too.

–  
Phillip “CynicalRyan” Gawlowski  
[http://cynicalryan.110mb.com/](http://cynicalryan.110mb.com/)

Rule of Open-Source Programming #6:

The user is always right unless proven otherwise by the developer.

---

<div class="post-metadata">

**Author:** ![rykkers](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/r/e5b9ba/32.png) [@rykkers](https://www.ruby-forum.com/u/rykkers)\
**Post date:** [April 10, 2007, 6:44am UTC](https://www.ruby-forum.com/t/comments-on-comments-was-re-getting-to-100-119/91494/5 "2007-04-10T06:44:31Z")

</div>

On Apr 10, 2007, at 1:06 PM, Phillip G. wrote:

> =begin  
> A  
> multi-  
> line  
> comment  
> =end
> 
> Add an rdoc behind the =begin, and it will be parsed by RDoc, too.

Thanks! I hadn’t seen that before!! I kinda wish it were a C style  
multiline comment syntax, but beggars can’t be choosers!