Mailing-List: contact derby-dev-help@db.apache.org; run by ezmlm
Precedence: bulk
Reply-To: <derby-dev@db.apache.org>
Received-SPF: pass (asf.osuosl.org: local policy)
Date: Fri, 24 Feb 2006 11:20:52 +0100
From: John Embretsen <John.Embretsen@Sun.COM>
Subject: Derby code convention (was: Re: [Db-derby Wiki] Update of
 "DerbyContributorChecklist" by RichardHillegas)
In-reply-to: <43FE1484.8010401@Sun.com>
To: derby-dev@db.apache.org
Reply-to: derby-dev@db.apache.org
Message-id: <217121167.20060224112052@Sun.com>
MIME-version: 1.0
Content-type: text/plain; charset=us-ascii
Content-transfer-encoding: 7BIT
References: <20060223193928.8637.18255@ajax.apache.org>
 <43FE1484.8010401@Sun.com>

Thursday, February 23, 2006, 9:01:08 PM CET, Kristian Waagan wrote:

> Apache Wiki wrote:
>> Dear Wiki user,
>> 
>> You have subscribed to a wiki page or wiki category on "Db-derby Wiki" for change notification.
>> 
>> The following page has been changed by RichardHillegas:
>> http://wiki.apache.org/db-derby/DerbyContributorChecklist
>> 
>> ------------------------------------------------------------------------------
>>   ||Copyright Notice||Every java file in your patch must start with the Apache [http://www.apache.org/licenses/LICENSE-2.0.html#apply  copyright notice]. See the existing Derby Java files for examples. ||
>>   ||Tests||Don't forget to include regression tests with your patch.||
>>   ||Coding Standards||The Derby community has not approved a common body of coding standards. Individual contributors have found the following standards useful: [http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html  Java Coding Standards] and [http://wiki.apache.org/geronimo/CodingStandards  Geronimo Coding Standards].||
>> + ||Comments||Make sure you comment your code.||
>> + ||Tabs||Set your tabs at 4 spaces. This was the original Cloudscape convention. With this setting your code should look readable.||
>>   

> Hi,

> I know the issue has been discussed before, but is it deliberate that 
> the checklist does not specify whether it is preferred to use tabs or 
> spaces for indentation?


I think the checklist comment on tabs needs to be changed/improved. In
fact, although we have not agreed upon a coding standard, I believe
there are some elements of such a standard that we definitely should
discuss and make "recommended practice" for derby contributors. Some
elements are (IMHO) ready for inclusion on the wiki (I'll add them later
if somebody else does not beat me to it, or disagree), while others are
subject to further discussion:


* White space - Tabs vs. spaces, length of tabs/"tabs", new code vs.
existing code (mixing tabs and spaces, or stick to whatever is in
there), etc.

* Line lengths - It seems that some reviewers/committers strongly
encourage contributors to wrap lines that are longer than 80 characters.
I think we should decide whether or not this should be a general policy
that we want to follow, and let people know by including this on the
wiki and/or the website.

* Comments/JavaDoc - Proper (up-to-date and correct) JavaDoc for all (?)
modified/added methods, classes, fields, including @param and @return
tags where appropriate, should be encouraged. I think it is necessary to
be this specific since people tend to forget these things, causing
delays and distracting the reviewers from the actual code changes.
Simply saying "Comment your code" on the wiki is not enough, in my
opinion.

* Copyright notice - It seems to me that we need to add some information
to the wiki checklist about updating the year in the copyright
statement, depending on when the file was created and last updated.

* No author tag - I guess everybody agrees on this now?


I think deciding upon a "recommended practice" to follow will save us
all some time in the long run, especially as we are getting closer to a
new release. I'll appreciate other's opinions on this.


-- 
John