Class comments!?

Michael Latta lattam at mac.com
Mon Oct 18 23:24:51 UTC 2004


I have been reading this thread with interest, as our team has a 
similar split on comments.

We have a code base that is between 2 and 7 years old, and has seen 
contributions from about 7 primary developers.

While there are places that have pretty good comment coverage (class 
and method comments).  There are whole chunks that have little or no 
comments.  Those areas that have no comments also almost universally 
have no developer level documentation.  The rationale is always the 
same: "the comments lie so why write them", or "who has time for that", 
or "just read the code to see what it does".

As commented ;-) on this thread, the point (as I see it) of comments or 
any documentation is not to say what the code does, but why it does it, 
and to give the reader of the code enough context to understand the 
code he/she is reading without having first to understand the whole 
thing in detail.  It is true that before making changes a programmer 
SHOULD understand the code in detail, but getting started on a whole 
new block of code is daunting without some good context and english 
description of how the pieces fit together and their roles in the whole 
endeavor.

This was driven home recently when the author / maintainer of a piece 
of our product was unavailable and I was asked to step in and make an 
enhancement.  Without comments (or documentation) to get started I was 
unable to be effective on short notice, and the task was put on hold 
waiting for the original developer to have time.  But, in those cases 
where the original developer is never going to have time (key person or 
just gone), the lack of contextual documentation is a huge risk to any 
organization.

I favor comments over documentation in some other repository because it 
increases the chance that the next poor sod to work on my code will be 
able to find it.  The word documents prepared at various points and 
placed under CM are never as easy to locate as comments in the code.

But the issue is not when will Squeak be worthy of study.  If you can 
not maintain it and refine it, it will never get there.  As an old time 
Smalltalker I hope it gets there, so I also hope that you do take the 
time to make it maintainable, otherwise it will be a large research 
effort that will collapse in on itself like so many others.

Just my $0.02 on a subject of recent concern.

Michael


On Oct 18, 2004, at 8:18 PM, lex at cc.gatech.edu wrote:

> Hey Goran, let's do indeed be careful not to drift down a slippery
> slope.  Quality does matter.
>
> Your water analogy seems to show our difference nicely.  You want a 
> high
> *percentage* of good, commented code.  I want a high *volume* of good
> code.  I think that uncommented code can still be pretty darned good,
> and thus that usually:
>
> 	X + (good, uncommented code)  >  X
> 	
> A decent way to getting a higher volume of commented code is to put
> uncommented code in there and thus make it easy for people to 
> contribute.
> If we reject code then we spoil the open source process we have going
> and make it hard for people to fix (comment) the code.  But of course,
> putting in uncommented code reduces the *percentage* of commented code,
> perhaps indefinitely.
>
> I agree the *percentage* of good code would be important if Squeak 
> were at
> a stage that it is worth picking it up and studying it.  However, I 
> think
> Squeak is at a much earlier stage right now.  It is likely that huge
> chunks of it will be tossed entirely before we get within reach of the
> next system that is really a crystaline beauty worthy of study.  In the
> meantime, functionality is extremely worthwhile, because it lets people
> do experiments.
>
> In short, why would the *percentage* of clear code be more important
> than the *volume* of clear code?
>
>
> -Lex
>




More information about the Squeak-dev mailing list