lex at cc.gatech.edu wrote:

>goran.krampe at bluefish.se wrote:
>  
>
>>>	X + (good, uncommented code)  >  X
>>>      
>>>
>>Eh... What? That is probably the silliest thing I have heard in this
>>thread. Really. ;)
>>
>It is an expression that volume matters.  "+" is combining two globs of
>code.  ">" means I like the left side better than the right.  You would
>not consider this to be a true formula in all cases, but I would.
>
Well, yes, the volume of *good* code matters. Without question, however, 
a little comment can be a big (huge?) help in deciding whether the 
submitted code is good or not in the first place. I don't think anyone 
is going to argue that good code without comments is better than the 
identical code with comments, right? So I hope that we are all in 
agreement on this at least?!

The simple fact is that it is widely agreed upon, both in industry and 
in academia, that commenting source code is better than not. Yes, some 
people are better at it than others... The real issue, however, seems to 
be whether uncommented code will be accepted for harvesting, yes? 
Historically the Squeak community has been willing to harvest 
uncommented code if the harvesters decide that it is worthy for 
inclusion in the image.

Personally, as someone who is trying to come up to speed in Squeak, it 
would be a big help if all the classes had at least a short comment as 
to their intended function so I didn't have to scrutinize and 
interrogate the source code itself. However, putting my own selfish 
interests aside, perhaps this would be a more fruitful discussion if 
those people passionate about the issue of commenting would provide some 
constructive suggestions on how this problem can be addressed.

Some options:
1) Modify the harvesting process. I have the impression that this is not 
widely supported due to the perception that it would create additional 
overhead and, hence, increase the time necessary to get code into the 
image. Nevertheless, requiring that original authors provide at least 
minimal comments when they submit new code is the most efficient way of 
reaching the goal of having useful comments throughout the codebase. 
Having put forth the effort to write the code in the first place, it is 
likely that a polite email along the lines of "Thanks for your 
submission, we would like to include it in the Squeak image provided 
that you furnish a few lines of comments." would be well received. An 
alternative is that the harvesters themselves add the comments, but I 
prefer the former approach.
2) Initiate a new effort (SqueakDoc?) to directly address uncommented 
code in the squeak image. This is by far the more laborious of the 
options, but likely necessary either way since the above would only 
address the new code submissions. If this is the only approach taken, it 
would truely be unfortunate if it led to the perception that people 
didn't have to provide comments since the SqueakDoc effort will do it 
for them.

I would like to see both of the above, but the first option is something 
that only the harvesters can really enforce. The second option is 
clearly necessary either way and is something that the wider community 
can decide to participate in if they care enough. Perhaps the community 
should simply vote on how they want the harvesting process to be run? 
This approach has worked very well within the Apache community and I 
would encourage people unfamilliar with the Apache process to spend a 
bit of time learning about it - there are some important lessons tobe 
learned in how to successfully foment a productive and valuable open 
source community. (This isn't to say that the Squeak community isn't 
both valuable and productive, but only to say that things could be 
improved...)

As a last point, I would like to note that having a well documented 
codebase will ultimately reduce the learning curve associated with 
contributing to the overall community - a learning curve which may very 
well prevent some people from contributing simply because they can't 
find their way around well enough to see what is going on. Keeping the 
bar to contributing unnecessarily high is a certain recipe for isolating 
the Squeak community from a potentially much broader user base.


Regards,
Elias
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20041019/65a838bd/attachment.htm