<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html;charset=ISO-8859-1">
<title></title>
</head>
<body>
<a class="moz-txt-link-abbreviated" href="mailto:lex@cc.gatech.edu">lex@cc.gatech.edu</a> wrote:<br>
<blockquote type="cite" cite="midE1CJxd2-0000mz-00@gadget.dnsalias.net">
<pre wrap=""><a class="moz-txt-link-abbreviated" href="mailto:goran.krampe@bluefish.se">goran.krampe@bluefish.se</a> wrote:
</pre>
<blockquote type="cite">
<blockquote type="cite">
<pre wrap=""> X + (good, uncommented code) > X
</pre>
</blockquote>
<pre wrap="">Eh... What? That is probably the silliest thing I have heard in this
thread. Really. ;)</pre>
</blockquote>
<pre wrap=""><!---->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.</pre>
</blockquote>
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?!<br>
<br>
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.<br>
<br>
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.<br>
<br>
Some options:<br>
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.<br>
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.<br>
<br>
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...)<br>
<br>
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.<br>
<br>
<br>
Regards,<br>
Elias<br>
</body>
</html>