Mailing-List: contact dev-help@geronimo.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@geronimo.apache.org
Received-SPF: neutral (asf.osuosl.org: local policy)
Message-ID: <450DB3EF.106@apache.org>
Date: Sun, 17 Sep 2006 14:45:35 -0600
From: Jeff Genender <jgenender@apache.org>
Reply-To: jgenender@apache.org
Organization: Apache Geronimo
User-Agent: Thunderbird 1.5.0.7 (Macintosh/20060909)
MIME-Version: 1.0
To: dev@geronimo.apache.org
Subject: Re: Writing Readable Code
References: <3DA110B6-BE10-4E29-BDA3-12AC3EC200BE@gmail.com>
In-Reply-To: <3DA110B6-BE10-4E29-BDA3-12AC3EC200BE@gmail.com>
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit

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 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.

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.

Jeff

Kevan Miller wrote:
> During the recent discussions regarding the Geronimo Development
> process, several people expressed some concern about moving away from
> RTC.  The biggest issue seemed to be that RTC insured multiple people
> reviewed new code. Having reviewed the code, the reviewers now
> understood and would be able to support the code (i.e. fix bugs).
> 
> This is certainly a valid concern. However, even though we're now
> following CTR, we all need to be making a concerted effort to provide
> the same level of review as commits are made.
> 
> No matter what process we're following, IMO, the best way to insure that
> people are reading *and* understanding your code is to write code that
> is easy to read and understand. This does not mean writing simple code.
> It simply means keeping the reader in mind and trying to make their job
> easier.
> 
> The single, most important thing, in my mind, is to provide clear and
> insightful comments to assist the reader. These don't need to be verbose
> tomes. They don't need to state the obvious. However, any assistance you
> can provide the reader is helpful. Describe the processing flow that
> methods are being invoked. What are the threading assumptions? Identify
> subtleties that a reader might not be aware of. Who are the potential
> callers? etc...
> 
> In case anyone is wondering -- I think we've been lacking in this
> department. I'd like to see simple comment guidelines incorporated into
> the Documentation Guidelines for our CTR process.
> 
> In my opinion, failure to appropriately comment new code is cause for a
> commit to be vetoed. I doubt that this will happen often. I expect that
> in most instances these issues can be resolved appropriately through
> simple discussion. Some basic rules-of-thumb are likely to help resolve
> any issues.
> 
> What do others think?
> 
> Specific ideas on comment guidelines? Javadoc-style comments for
> APIs/SPIs, etc? What types of comments should be expected?
> 
> --kevan
>