On Sep 17, 2006, at 4:45 PM, Jeff Genender wrote:
I am not supportive of forcing javadoc, and I would not like to make
that a reason for veto. If folks aren't following guidelines to good
coding practices and the code is illegible, then I think we can help
mentor following generally accepted practices. I have read a lot of
code and for 99% of the time, the code is understandable enough.
I'm hesitant to be too dogmatic on any rules. Personally, I think
javadoc for API/SPI classes/interfaces is reasonable and desirable.
I'd give people more leeway on internal apis and implementation (the
majority of our code).
Sure, most code can be read. However, often times you can read it
more quickly with a little assist. Also, sometimes reading code means
unknowingly reading "bugs". Also, it can be difficult to understand
the context in which code is invoked. For example, understanding the
threading context of a method invocation can be difficult. When a
method is a part of an overall larger picture, pulling that context
together can be extremely useful to the reader.
I think if CTR is the order, then people who make fairly large commits
should engage in some thorough discussion of what they are doing on
the
lists. Javadoc should not be a substitute for this a s javadoc is not
engaging the community, which is most important.
Absolutely agreed that comments are no substitute for communicating
changes to the community. However, they can also enhance that
community communication.
OTOH, it would be nice if we did document a little bit more. But I
would not like to see it as a gate to getting code in.
In my experience, the probability of good comments being added to
code post the initial commit is extremely low. If you think it would
be good to document more, how do you see that happening?
--kevan
