src/documentation/content/xdocs/resolutions/res001.xml - poi - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>
 <!--
    ====================================================================
    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.
    ====================================================================
 -->
 <!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>
	<?xml version="1.0" encoding="UTF-8"?>
	<!--
	====================================================================
	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.
	====================================================================
	-->
	<!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>