On Thu, 14 Oct 2004 11:07:45 -0700, Tim Rowledge <tim at sumeru.stanford.edu>  
wrote:

> Whilst a few small methods might be completely self explanatory as to
> what they actually do, it is extremely rare that this is a complete
> explanation of what the code is _supposed_ to do.

Yes, sort of my point, really. If the code isn't doing what it's supposed  
to, the comments can be misleading. I generally only comment when I've  
been clever, and I'm only clever when I'm not clever enough to figure out  
how to be simple.<s>

> I claim that the
> fantasy of 'self commenting code' is just that - a fantasy. Usually
> promulgated by lazy buggers that take the attitude summed u in one of
> my auto-magic siglines "Comments? Why do you think it's called code?"

You may be right, at least in most csess. Not in mine, however. I start  
with documentation, at least on a project of any size. I still don't  
comment my code, though.

> Longer methods have exponentially more need for commentary explaining
> the intent, known limitations, unfinished parts etc. It's real simple;
> stick to Adele's Rule - "if it isn't documented, it doesn't exist" with
> the corollary that "and if it doesn't exist, just what did you get paid
> for?".  Code is never, ever, written just for you. And even if
> 579035162 Smith is the only person that ever sees it, s/he is not the
> same person in six months time when the original context is forgotten.

This is the flaw with your argument, in my experience. I wrote code for  
some clients in...1993, I think it was. I was called in to make changes in  
1998. It was a DOS program, and in the interim I had switched to OS/2 and  
then to Windows '98. I had no problems understanding it or maintaining it.  
This was old Turbo Vision code, which was pretty nasty stuff--Borland's  
first attempt to shoehorn objects onto Pascal. Tons of pointers,  
indirection, typecasting, more parentheses than Lisp.

But I'd used good design when building it--a lot of things I had picked up  
in Smalltalk--and I knew the problem domain very well. I had tight control  
over the data and could make my own rules, as long as I produced the right  
results. (A rare instance where the results were perfectly well known, in  
their entirety, in advance.)

In my experience, it's really inadequate description of the problem that's  
the issue. I have said in the past, and I believe it more and more, that  
programmers should never have to--or be allowed to--make decisions.<s>

> If you ever work for me (and ultimately all of you will, sometime) you
> will need to provide clear, meaningful comments for just about every
> possible bit of code or face Bun-Bun (www.sluggy.com) as punishment.

I guess I won't be working for you<s>. I've seen people do this:

I := I + 1; {Add 1 to I}

You couldn't make me. Nu uh. Nope. No way.