On Sat, 16 Oct 2004 09:04:19 -0400, Jon Hylands <jon at huv.com> wrote:

> I think you picked a bad example. How about:

So, we agree that it isn't necessary to comment every line of code, then.

I think we're disagreeing on semantics. I don't think of this:

> PositionableStream >> #upToAll: aCollection
> 	"Answer a subcollection from the current access position to the
> occurrence (if any, but not inclusive) of aCollection. If aCollection is
> not in the stream, answer the entire rest of the stream."

as commenting the code. I see this as documenting the intent of the  
method. I consider "commenting the code" to be describing what a  
particular line or block does, and this is what I object to, except as  
mentioned, where the code is subtle or clever.

So, what about commenting the method, as here? Good or bad or redundant?  
Let's consider:

> its a whole lot easier to just read the comment. The comment is very
> concise, and it tells you exactly what the method does.

OK, so what's good about it is that it might tell you what the function  
does. What's bad about it is that it has no semantic value. There's no  
guarantee that it actually describes what the method does or what it's  
supposed to do. Having read bugged comments, I can attest this is a real  
issue.

Now, let's look at the placement: We can agree that it's good to see the  
code thereIn a polymorphic system of any depth, are there not going to be  
MANY #upToAll routines? And couldn't they all rightfully carry that  
comment? And, if you planned a design change, should a comment like this  
one be reflected throughout the hierarchy?

OK, this is good! What would we think about a system like this:

At the hierarchy level (the base class), you have an #upToAll method, and  
it has this comment:

"Answer a subcollection from the current access position to the
occurrence (if any, but not inclusive) of aCollection. If aCollection is
not in the stream, answer the entire rest of the stream."

Which then carries forward, uneditable, to all the children--shows up in a  
different color. Now the child classes can add their own comments about  
exceptions and variations. You could create a reference document from this  
that you could actually use to document the design philosohpy.

I can see that working very well.
	
> As for your example regarding zValue, I expect to see that sort of
> documentation in the class comment.

Class comments are all right. They're "external" in the sense that I mean  
it.

And again this goes back to what I was saying about languages respecting  
design and environment. Though I suppose this could be done with clever  
comment codes that an external tool could read.

> Maybe you like external documentation -- I prefer everything I need to  
> use
> a class like Stream to be in the image, and easily accessible with all  
> the
> nice cross-referencing tools that Smalltalk has. I certainly don't want  
> to
> have to go open some word document or web page and waste time looking for
> PositionableStream >> #upToAll: -- I'm already looking at it.

What I mean by "external": not in the code. (And by "code", here, I mean  
"methods". I don't consider class definition as code, even though it  
actually is in Smalltalk.<s>) It's fine if it's in the image. In  
Smalltalk, it ought to to be in the image. You could have an object that  
documented your classes, and probably one that synced up with your browser.

But we've gotten away from what I perceived the initial argument about  
comments to be: Some people champion commenting EACH LINE of code. What  
I've been trying to communicate is that that's not usually necessary, and  
it's often a bad idea. Maybe you disagree, but so far, I've seen defense  
of "macro"-comments, which I'm pro.

As for internal vs. external, when things in OOPland =work=, I don't have  
to look at someone else's code. I understand what it does and can use it  
=without= digging into its internals. I think it's very important that  
that #upToAll comment be externally accessible.