commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Morgan Delagrange <mdela...@yahoo.com>
Subject Re: [VOTE] Adopt Minimal Coding Standards
Date Mon, 19 Aug 2002 19:28:55 GMT

--- Nicola Ken Barozzi <nicolaken@apache.org> wrote:

<snip/>
 
> I propose that we change the Commons coding
> convention standards so that 
> they are more pragnatic and geared towards
> respecting the projects from 
> which they originated.

It's a little early for a vote, I think.  Let's hash
out the proposal first.

> This doesn't mean that massive code reformattig
> should never be done, 
> but that it's not recomended, and that it should be
> decided beforehand.
> 
> The new standards would be according to the
> resolution adopted by the 
> POI project:
>
http://jakarta.apache.org/poi/resolutions/res001.html
> 
> "
> 
>     1. All classes and interfaces MUST have, right
> at the beginning, the 
> ApacheCommons License .
> 
>     2. All classes and interfaces MUST include class
> javadoc. 
> Conventionally, this goes after the package and
> imports, and before the 
> start of the class or interface. The class javadoc
> MUST have at least 
> one @author tag.
> 
>     3. All methods that are accessible outside the
> class MUST have 
> javadoc comments. In other words, if it isn't
> private, it MUST have 
> javadoc comments. Simple getters can consist of a
> simple @return tag; 
> simple setters can consist of a simple @param tag.
> Anything else 
> requires some verbiage plus all the standard javadoc
> tags as 
> appropriate. You MUST include @throws or @exception
> for any non-runtime 
> exceptions, and you SHOULD document any runtime
> exceptions you expect to 
> throw. @throws/@exception tags SHOULD include an
> explanation of why that 
> exception would be thrown. If your method might
> return null, you MUST 
> say so. An accompanying explanation of the
> circumstances for doing so 
> would be nice.
> "

That sounds good to me.

> They would also contain the following:
> 
> "
> Every change to the code should not alter
> substantially the coding 
> conventions adopted by the original author.
> It is reccomended that classes created within
> Commons and not taken from 
> other projects follow the Sun Coding Convention
> guidelines.
> "

How about something more like:

  Each Commons component should use an internally
  consistent and documented coding style.  If a 
  component does not specify its coding style, 
  the Sun Coding Convention guidelines are 
  assumed.

> 
> -- 
> Nicola Ken Barozzi                  
> nicolaken@apache.org
>              - verba volant, scripta manent -
>     (discussions get forgotten, just code remains)
>
---------------------------------------------------------------------
> 
> 
> --
> To unsubscribe, e-mail:  
> <mailto:commons-dev-unsubscribe@jakarta.apache.org>
> For additional commands, e-mail:
> <mailto:commons-dev-help@jakarta.apache.org>
> 


=====
Morgan Delagrange
http://jakarta.apache.org/taglibs
http://jakarta.apache.org/commons
http://axion.tigris.org
http://jakarta.apache.org/watchdog

__________________________________________________
Do You Yahoo!?
HotJobs - Search Thousands of New Jobs
http://www.hotjobs.com

--
To unsubscribe, e-mail:   <mailto:commons-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:commons-dev-help@jakarta.apache.org>


Mime
View raw message