On Sat, 16 Oct 2004 01:57:55 -0700, Blake <blake at kingdomrpg.com> wrote:

> I would like to point out here that Squeak is largely uncommented. If I  
> take an object at pseudo-random, say B3DPrimitiveEdge, and look at zValue,  
> I see:
> 
> zValue
> 	^ zValue
> 
> Y'all may want a "returns zValue" comment there, but I'd much rather a  
> document that explains Z-order and how it relates to balloon positioning.

I think you picked a bad example. How about:

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."

	| startPos endMatch result |
	startPos := self position.
	(self match: aCollection) 
		ifTrue: [endMatch := self position.
			self position: startPos.
			result := self next: endMatch - startPos -
aCollection size.
			self position: endMatch.
			^ result]
		ifFalse: [self position: startPos.
			^ self upToEnd]

You could probably figure out what the method does by reading the code, but
its a whole lot easier to just read the comment. The comment is very
concise, and it tells you exactly what the method does.

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

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.

Later,
Jon

--------------------------------------------------------------
   Jon Hylands      Jon at huv.com      http://www.huv.com/jon

  Project: Micro Seeker (Micro Autonomous Underwater Vehicle)
           http://www.huv.com