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
|