geronimo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Kevan Miller <>
Subject Re: Writing Readable Code
Date Mon, 18 Sep 2006 16:18:24 GMT

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?


View raw message