2003-04-23 20:53:41 -04:00
|
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
2007-01-15 18:11:09 -05:00
|
|
|
<!--
|
|
|
|
|
====================================================================
|
|
|
|
|
Licensed to the Apache Software Foundation (ASF) under one or more
|
|
|
|
|
contributor license agreements. See the NOTICE file distributed with
|
|
|
|
|
this work for additional information regarding copyright ownership.
|
|
|
|
|
The ASF licenses this file to You under the Apache License, Version 2.0
|
|
|
|
|
(the "License"); you may not use this file except in compliance with
|
|
|
|
|
the License. You may obtain a copy of the License at
|
|
|
|
|
|
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
|
|
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
|
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
|
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
|
|
|
See the License for the specific language governing permissions and
|
|
|
|
|
limitations under the License.
|
|
|
|
|
====================================================================
|
|
|
|
|
-->
|
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>
|
