User: schaefera
Date: 01/07/19 18:02:08
Added: . guidelines.jsp
Log:
Guidelines web site to explain this and make it easier to read.
Revision Changes Path
1.1 newsite/guidelines.jsp
Index: guidelines.jsp
===================================================================
<jsp:include page="head.jsp" flush="true" />
<jsp:include page="slogan.jsp" flush="true" >
<jsp:param name="SLOGAN" value="CONTRIBUTE TO JBOSS: Guidelines"/>
</jsp:include>
<!-- CONTENT -->
<p class="head">DEVELOPER CODING GUIDELINES</p>
<p class="text">
This Guidelines are here to make the JBoss code more readable. Because of the
"Age" of JBoss there will be
always some code around which does not follow the guidelines but over time
this may become less and less.
</p>
<p class="text">
To see a template for a class file go to the JBoss-Source
:<jboss>/src/etc/class.java and for an interface:
<jboss>/src/etc/interface.class.
</p>
<p class="head">Layout</p>
<p class="text">
<ul>
<li>
Identation: 3 Spaces (no Tabs because they look ugly in "dump" editors
like HTML pages (online CVS) )
</li>
<li>
Comments: line up comments on the left hand side (also Javadocs)
</li>
<li>
Grouping: Group members, methods etc. according to the templates and use
the template's comments to
separate them.
</li>
</ul>
</p>
<p class="head">General Code</p>
<p class="text">
The first part of a JBoss class should contain the Copyright comment:
<pre>
/*
* JBoss, the OpenSource EJB server
*
* Distributable under LGPL license.
* See terms of license at gnu.org.
*/
</pre>
</p>
<p class="text">
Next part is the package definition. Please use <b>NO ABBREVIATIONS</b> and
follow the Java guidelines.
</p>
<p class="text">
Now add the external classes import statement. Please use always fully
qualified imports (no *) because
then everyone knows which class comes from which package. When you have a
conflict then import none or
the best one and fully qualify the other class(es) when you use them (example:
java.util.Date and java.sql.Date).
</p>
<p class="text">
Add the JavaDoc Documentation for the main class which looks like this:
<pre>
/**
* <description>
*
* @see <related>
* @author <a href="mailto:{email}">{full name}</a>.
* @author <a href="mailto:[EMAIL PROTECTED]">Marc Fleury</a>
* @version $Revision: 1.1 $
*
* <p><b>Revisions:</b>
*
* <p><b>yyyymmdd author:</b>
* <ul>
* <li> explicit fix description (no line numbers but methods) go beyond the
cvs commit message
* </ul>
* eg:
* <p><b>20010516 marc fleury:</b>
* <ul>
* <li> Ask all developers to clearly document the Revision, changed the
header.
* </ul>
*/
</pre>
Instead of "@see" you can also use "{@link ...}" inside the comments (inline
reference).
<b>ALWAYS add these comments, the developer after you will love it and
hopefully do his/her part as well</b>.
</p>
<p class="text">
Document all public (and mostly protected) members and methods in the class
with JavaDoc except you did not
add new functionality during overwriting a method (comming from an Interface
or a base class). Especially note
<ul>
<li>
When Parameter can or cannot be null and also what it means when null is
allowed
</li>
<li>
When Return values can be or are never null
</li>
<li>
Document side effects
</li>
<li>
Usefull is also when you mention if and where another method or the
overwritten method is called. Because
this is open-source it is not that important but when you only rely on the
documentation it can avoid
endless calls or other avoid mistakes when you have to call the
overwritten method.
</li>
</ul>
</p>
<p class="head">Coding a Class</p>
<p class="text">
<pre>
/*
* JBoss, the OpenSource EJB server
*
* Distributable under LGPL license.
* See terms of license at gnu.org.
*/
package x;
//EXPLICIT IMPORTS
import a.b.C1; // GOOD
import a.b.C2;
import a.b.C3;
// DO NOT WRITE
import a.b.*; // BAD
/**
* <description>
*
* @see <related>
* @author <a href="mailto:{email}">{full name}</a>.
* @author <a href="mailto:[EMAIL PROTECTED]">Marc Fleury</a>
* @version $Revision: 1.1 $
*
* <p><b>Revisions:</b>
*
* <p><b>yyyymmdd author:</b>
* <ul>
* <li> explicit fix description (no line numbers but methods) go beyond the
cvs commit message
* </ul>
* eg:
* <p><b>20010516 marc fleury:</b>
* <ul>
* <li> Ask all developers to clearly document the Revision, changed the
header.
* </ul>
*/
// DO NOT USE "TAB" TO INDENT CODE USE *3* SPACES FOR PORTABILITY AMONG EDITORS
public class X
extends Y
implements Z
{
// Constants -----------------------------------------------------
// Attributes ----------------------------------------------------
// Static --------------------------------------------------------
// Constructors --------------------------------------------------
// Public --------------------------------------------------------
public void startService() throws Exception
{ // Use the newline for the opening bracket so we can match top and bottom
bracket visually
Class cls = Class.forName(dataSourceClass);
vendorSource = (XADataSource)cls.newInstance();
// JUMP A LINE BETWEEN LOGICALLY DISCTINT **STEPS** AND ADD A LINE OF COMMENT
TO IT
cls = vendorSource.getClass();
if(properties != null && properties.length() > 0)
{
try
{
}
catch (IOException ioe)
{
}
for (Iterator i = props.entrySet().iterator(); i.hasNext();)
{
// Get the name and value for the attributes
Map.Entry entry = (Map.Entry) i.next();
String attributeName = (String) entry.getKey();
String attributeValue = (String) entry.getValue();
// Print the debug message
log.debug("Setting attribute '" + attributeName + "' to '" +
attributeValue + "'");
// get the attribute
Method setAttribute =
cls.getMethod("set" + attributeName,
new Class[] { String.class });
// And set the value
setAttribute.invoke(vendorSource,
new Object[] { attributeValue });
}
}
// Test database
vendorSource.getXAConnection().close();
// Bind in JNDI
bind(new InitialContext(), "java:/"+getPoolName(),
new Reference(vendorSource.getClass().getName(),
getClass().getName(), null));
// We are done
log.log("XA Data source "+getPoolName()+" bound to java:/"+getPoolName());
}
// Z implementation ----------------------------------------------
// Y overrides ---------------------------------------------------
// Package protected ---------------------------------------------
// Protected -----------------------------------------------------
// Private -------------------------------------------------------
// Inner classes -------------------------------------------------
}
</pre>
</p>
<p class="head">Coding a Interface</p>
<p class="text">
<pre>
/*
* JBoss, the OpenSource EJB server
*
* Distributable under LGPL license.
* See terms of license at gnu.org.
*/
package x;
//EXPLICIT IMPORTS
import a.b.C1; // GOOD
import a.b.C2;
import a.b.C3;
// DO NOT WRITE
import a.b.*; // BAD
/**
* <description>
*
* @see <related>
* @author <a href="mailto:{email}">{full name}</a>.
* @author <a href="mailto:[EMAIL PROTECTED]">Marc Fleury</a>
* @version $Revision: 1.1 $
* Revisions:
*
* <p><b>Revisions:</b>
*
* <p><b>yyyymmdd author:</b>
* <ul>
* <li> explicit fix description (no line numbers but methods) go beyond the
cvs commit message
* </ul>
* eg:
* <p><b>20010516 marc fleury:</b>
* <ul>
* <li> Ask all developers to clearly document the Revision, changed the
header.
* </ul>
*/
// DO NOT USE "TAB" TO INDENT CODE USE *3* SPACES FOR PORTABILITY AMONG EDITORS
public interface X
extends Y
{
// Constants -----------------------------------------------------
// Static --------------------------------------------------------
// Public --------------------------------------------------------
public ReturnClass doSomething()
throws ExceptionA, ExceptionB;
} </pre>
</p>
<jsp:include page="navigation.jsp" flush="true" />
_______________________________________________
Jboss-development mailing list
[EMAIL PROTECTED]
http://lists.sourceforge.net/lists/listinfo/jboss-development
