2003-04-23 20:53:41 -04:00
|
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
2004-04-09 09:05:39 -04:00
|
|
|
<!-- Copyright (C) 2004 The Apache Software Foundation. All rights reserved. -->
|
2003-04-23 20:53:41 -04:00
|
|
|
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
|
|
|
|
|
|
|
|
|
|
<document>
|
|
|
|
|
<header>
|
|
|
|
|
<title>POI Resoluton</title>
|
|
|
|
|
<subtitle>Resolution 001 - Minimal Coding Standards</subtitle>
|
|
|
|
|
<authors>
|
|
|
|
|
<person name="Andrew C. Oliver" email="acoliver@apache.org"/>
|
|
|
|
|
</authors>
|
|
|
|
|
</header>
|
|
|
|
|
|
|
|
|
|
<body>
|
|
|
|
|
<section><title>Resolution 001 - Minimal Coding Standards</title>
|
|
|
|
|
<section><title>Majority Position</title>
|
|
|
|
|
<p>
|
|
|
|
|
As the POI project has grown the "styles" used have become more
|
|
|
|
|
varied, some see this as a bad thing, but in reality it
|
|
|
|
|
can be a good thing. Each can learn from the different
|
|
|
|
|
styles by working with different code. That being said
|
|
|
|
|
there are some universal "good quality" guidelines that
|
|
|
|
|
must be adopted on a project of any proportions.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
Marc Johnson Authored the following resolution:
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
On Tue, 2002-01-08 at 22:23, Marc Johnson wrote:
|
|
|
|
|
Standards are wonderful; everyone should have a set.
|
|
|
|
|
Here's what I propose for coding standards for POI WRT comments (should I
|
|
|
|
|
feel the need, I'll post more of these little gems):
|
|
|
|
|
</p>
|
|
|
|
|
<ol>
|
|
|
|
|
<li>
|
|
|
|
|
All classes and interfaces MUST have, right at the beginning, the POI
|
|
|
|
|
License (see poi/doc/LICENSE).
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
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
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
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.
|
|
|
|
|
</li>
|
|
|
|
|
</ol>
|
|
|
|
|
</section>
|
|
|
|
|
<section><title>Amendments (informal by extension and not by vote)</title>
|
|
|
|
|
<section><title>License</title>
|
|
|
|
|
<p>
|
|
|
|
|
As opposed to the formerly used POI License which was
|
|
|
|
|
based on the Apache Public License, now that POI is part of
|
|
|
|
|
Jakarta, use the APL 1.1 for the header. Currently, the
|
|
|
|
|
Apache Software Foundation requires us to use the full
|
|
|
|
|
long version.
|
|
|
|
|
</p>
|
|
|
|
|
</section>
|
|
|
|
|
<section><title>2 cents</title>
|
|
|
|
|
<p>
|
|
|
|
|
Tip: No laughing or joking allowed in conversations regarding coding
|
|
|
|
|
standards.
|
|
|
|
|
Any mail on coding standards will be treated very seriously,
|
|
|
|
|
and sent here with a RTFM.
|
|
|
|
|
</p>
|
|
|
|
|
</section>
|
|
|
|
|
</section>
|
|
|
|
|
<section><title>Dissent</title>
|
|
|
|
|
<p>
|
|
|
|
|
The motion was passed unanimously with no negative or
|
|
|
|
|
neutral votes.
|
|
|
|
|
</p>
|
|
|
|
|
</section>
|
|
|
|
|
<section><title>Comments</title>
|
|
|
|
|
<p>
|
|
|
|
|
Andy didn't feel like going through his mail and sucking
|
|
|
|
|
out the comments.. If there is anything you feel should
|
|
|
|
|
be added here do it yourself ;-).
|
|
|
|
|
</p>
|
|
|
|
|
</section>
|
|
|
|
|
</section>
|
|
|
|
|
</body>
|
|
|
|
|
</document>
|
