Class comments!?

Tim Rowledge tim at sumeru.stanford.edu
Fri Oct 15 18:41:27 UTC 2004


Blake <blake at kingdomrpg.com> wrote:

> 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>
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?

> 
> > 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.
Good on you for starting with doc. A rare thing in my experience.

> 
> > 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.
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
:-) But what about somebody else? Could they have picked up your code
and made sense of it?

> 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>
An interesting way of putting it and in some senses I agree. That
adequate description of the problem is a _huge_ issue. Boundary
conditions - probably the defining bugbear of my professional life -
are hardly ever considered. 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!

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

> 
> > 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.
It depends what the intent of the statement is; as a bald line of code
it looks pretty dumb to comment it like that. 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. 


tim
--
Tim Rowledge, tim at sumeru.stanford.edu, http://sumeru.stanford.edu/tim
Useful random insult:- Cackles a lot, but I ain't seen no eggs yet.



More information about the Squeak-dev mailing list