On Fri, 15 Oct 2004 11:41:27 -0700, Tim Rowledge <tim at sumeru.stanford.edu>  
wrote:

> Well, yes and no. It's certainly important to try to be simple but even
> simple code is likely to need some explanation of what the intent it.
> Code expresses that _actual_ function not the desired function. What
> about the limits, the assumed preconditions, all that stuff?

Those should be apparent from the code; the intent should be documented  
outside the code, as should the limitations, etc.

> Good on you for starting with doc. A rare thing in my experience.

I'm the only one I know who does it. But I point the practice out a lot in  
books and articles. I like to know where I'm going before I head there.

> When I was young I could do things like that too - including a
> multi-hour debugging session by phone, from memory with no machine
> available. Unless you're very lucky memory will fade with hair colour

Hey, I've done that! <s> To be honest, I've never been able to do that by  
remembering how I coded something, only by imagining how I =would= have  
coded it. (Seriously, it's not "I put the foo in the bar", it's, "Well, I  
would've put the foo in the bar.")

> :-) But what about somebody else? Could they have picked up your code
> and made sense of it?

In that case, as far as I know, nobody tried. However, I've included code  
with all of my books, and have plenty of indication that my style isn't  
incomprehensible, despite lots of uncommented code. (Of course, there was  
a BOOK outside the code. And the book had code snippets. You could say  
that the code was inverted-ly commented.<s>)

> An interesting way of putting it and in some senses I agree. That
> adequate description of the problem is a _huge_ issue.

I would probably say it is =the= issue.

> Boundary
> conditions - probably the defining bugbear of my professional life -
> are hardly ever considered.

You know, I've said the same thing on more than one occasion, often to  
blank stares from other programmers.

> Tests usually only test what happens when
> it works and almost never see what happens when it fails - does that
> algorithm crash the machine if a 0 goes in? Dang, the program dumped!

Hey, my pappy always taught me: test for 0, 1 and many.<S>

> One of the big problems with problem descriptions and specs is that
> they are often provided by marketing/sales types with no clue about
> engineering. Or worse...

I'm working with some (very cool) guys who don't know a thing about  
software engineering. When I entered the project it was "almost done",  
though they hadn't considered MOST of the their problem domain at all. As  
I've told them, we have two big issues: No spec (literally) and unreliable  
tools.

>>
>> I := I + 1; {Add 1 to I}
>>
>> You couldn't make me. Nu uh. Nope. No way.
> It depends what the intent of the statement is; as a bald line of code
> it looks pretty dumb to comment it like that.

I've seen it done!

> But what if adding 1 to
> an index is needed to convert from 0 based array indices to 1 based?
> Commenting a reminder of that might be a very valuable action, saving
> many hours of debugging for some poor sod. Commenting the _intent_
> gives the clue.

Funny you should say that: as a Basic-Pascal-PL/I guy I got very used to  
1-based lists. Years of having to add "-1" to all my code has disabused me  
of the notion that they're a good idea. But I digress.

I would say that documenting "I := I + 1" is going after the wrong target.  
That "I := I + 1" does not exist in a vacuum. (I've seen translators do  
this: They look at a word and ask "what does it mean", when there's no way  
of knowing without knowing the whole sentence, and possibly the preceding  
paragraph.)

The big issue is that you're converting from one kind of base to another,  
right? This suggests several situations:

1. You're trying to make agree your array and someone else's array. Your  
standard should be well-documented (and will be repeatedly reinforced as  
others look through your code, yes?) and so should interactions with  
objects that don't meet that standard. As a real example of this, in the  
many years I worked with Pascal but had to make it conform to some other  
API, the rule was always simple and apparent: internal, 1-based; external  
0-based.

Now, I could have put (hundreds) of little comments in there to note every  
time I had to do this. What do I lose? Well, my code gets a lot more  
cluttered. And then what if I forget once? You talk about saving the poor  
sod hours of debugging--what does he make of that one time where I forget?  
Does he end up racking his brain trying to figure out why this case is  
different? If he knows the rules mentioned above (which is the sort of  
thing I document externally), then he understands and is free to think for  
himself. If I put the comment in, instead of just understanding the code,  
he has to try to understand THREE things: Whether the code is correct,  
whether the comment is correct, and whether the comment and code actually  
agree!

Maybe I'm the only one who's ever had that happen. But I have most  
certainly opened code and besides finding out-of-date comments, or obscure  
comments attached to basically simple code, I've found elaborate  
descrpitions of what code is supposed to do and how, only to find out that  
the comment was wrong.

2. Another possible situation I see is that you're careless about starting  
your array at 0 or 1. Bad idea.<s>

3. A situation I could see, that I might even  consider acceptable, is you  
have a bunch of different indices, based on some content significance. In  
that circumstance, alignment code would be expected in EVERY case. Again,  
no need for line-by-line comment.

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 don't think we're really disagreeing here about good documentation. Just  
quibbling over where to put it. I want--especially in Smalltalk where each  
method is discretely displayed--a document that gives me an overall view  
so that I can understand the individual elements do. I consider  
understanding the individual elements the entry fee. (Wow, there's another  
job I wish I had gotten, but which never came to fruition: I was on  
retainer for a company that was going to make its money documenting  
classes. Was a great idea.)