Now that there are more people working within Jetspeed I drew up a
document that we should follow in regards to coding
conventions/standards. If anyone has any comments please let me know.
Also, don't read anything into this. It is only meant to improve the
quality of future code and I am not saying anything about existing code
:)
Kevin
-----------------------------
<?xml version="1.0"?>
<!--
Author: [EMAIL PROTECTED]
$Id: coding-conventions.xml,v 1.2 2000/05/05 00:32:04 burton Exp $
-->
<document>
<header>
<title>Coding Standards</title>
<subtitle>Coding Standards</subtitle>
<authors>
<person name="Kevin A. Burton" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<p>
As more developers submit code to Jetspeed, it is important that we
all adhere
to the same types of coding styles. This document was created to
provide a
set of guidelines for future development.
</p>
<s1 title="Use of JavaDoc">
<ul>
<li>
Use javadoc on all methods.
</li>
<li>
If you define an interface and then provide and
implementation of this
interface use @see tags to point Javadoc back to the
interface method.
You should then keep all your Javadoc defined in the
interface so that
it isn't duplicated in your implementation.
</li>
<li>
Describe all return values (@returns), method parameters
(@param) and
Exceptions (@throws)
</li>
<li>
If you define a new method make sure to include a
package.html which
defines what this package does.
</li>
<li>
If you make a change to a method or class, please add
yourself to the
@author tags. Please also include your e-mail address.
</li>
</ul>
</s1>
<s1 title="Java Syntax">
<ul>
<li>
Please use spaces within methods, and parameters:
<source test=""><![CDATA[
Instead of:
this.test(true,true,"test",true);
please use:
this.test( true, true, "test", true );
]]></source>
</li>
<li>
Use of brackets. Some developers have personal a preference
to
how they place brackets within their source code:
<source test=""><![CDATA[
if ( true ) {
//body
}
or
if ( true )
{
//body
}
]]></source>
Please choose whatever style you want for new files but you
should
maintain the existing style of source you wish to modify.
</li>
<li>If you have a method with multiple parameters, seperate
them across
multiple lines.
<source test=""><![CDATA[
Instead of having a long list of parameters on one one line, break
your parameter
list across several lines:
private final PortletSet getPortlets( Portlets portlets, RunData
rundata, boolean application, boolean applicationsOnly ) {
}
private final PortletSet getPortlets( Portlets portlets,
RunData rundata,
boolean application,
boolean applicationsOnly )
{
}
]]></source>
</li>
</ul>
</s1>
<s1 title="Misc.">
<ul>
<li>
File structuring. Try to keep everything organized
according to the
current directory structure. For example do no put
documentation
within the ./src/java directory.
</li>
<li>
Try not throw a basic java.lang.Exception. All Exceptions
thrown within
Jetspeed which describe an internal problem should extend
org.apache.jetspeed.util.JetspeedException (see
PortletException.java)
</li>
</ul>
</s1>
</body>
</document>
--
Kevin A Burton ([EMAIL PROTECTED])
http://relativity.yi.org
Message to SUN: "Please Open Source Java!"
"For evil to win is for good men to do nothing."
--
--------------------------------------------------------------
Please read the FAQ! <http://java.apache.org/faq/>
To subscribe: [EMAIL PROTECTED]
To unsubscribe: [EMAIL PROTECTED]
Archives and Other: <http://java.apache.org/main/mail.html>
Problems?: [EMAIL PROTECTED]
