quintonm 2003/03/12 13:04:34
Modified: xdocs/common code-standards.xml
Log:
Adding coding standards talked about on the dev list.
Revision Changes Path
1.5 +92 -10 jakarta-turbine-site/xdocs/common/code-standards.xml
Index: code-standards.xml
===================================================================
RCS file: /home/cvs/jakarta-turbine-site/xdocs/common/code-standards.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- code-standards.xml 7 Apr 2002 03:16:30 -0000 1.4
+++ code-standards.xml 12 Mar 2003 21:04:34 -0000 1.5
@@ -6,6 +6,7 @@
<title>Coding Standards</title>
<author email="[EMAIL PROTECTED]">Jon S. Stevens</author>
<author email="[EMAIL PROTECTED]">Jason van Zyl</author>
+ <author email="[EMAIL PROTECTED],net">Quinton McCombs</author>
</properties>
<body>
@@ -39,7 +40,7 @@
</p>
<source test=""><![CDATA[
-if ( foo )
+if (foo)
{
// code here
}
@@ -57,7 +58,7 @@
// code here
}
-while ( true )
+while (someCondition)
{
// code here
}
@@ -102,18 +103,36 @@
5. JavaDoc <strong>MUST</strong> exist on all methods. If your code
modifications use an existing class/method/variable which lacks
JavaDoc, it is required that you add it. This will improve the
-project as a whole.
+project as a whole. For guidelines on how to write proper
+JavaDocs, see
+<a href="http://java.sun.com/j2se/javadoc/writingdoccomments/index.html";>
+Sun's guidelines</a>
</p>
<p>
-6. The Jakarta/Turbine License <strong>MUST</strong> be placed at the top
+6. When writing javadocs for variables, try to keep the comment on just
+one line.
+</p>
+<source><![CDATA[
+/** Documentation of this variable */
+private int myVariable;
+
+/**
+ * If the documentation of the variable is enough to occupy multiple
+ * lines, then this form of comment is also perfectly acceptable.
+ */
+private int myVariable;
+]]></source>
+
+<p>
+7. The Jakarta/Turbine License <strong>MUST</strong> be placed at the top
of each and every file.
</p>
<p>
-7. If you contribute to a file (code or documentation), add yourself to the
-authors list at the top of the file. For java files the
-preferred Javadoc format is:
+8. If you contribute to a file (code or documentation), add yourself to the
+authors list at the top of the file. You should add yourself to the end of
+the list of authors. For java files the preferred Javadoc format is:
</p>
<source><![CDATA[
@@ -121,7 +140,7 @@
]]></source>
<p>
-8. All .java files should have a @version tag like the one below.
+9. All .java files should have a @version tag like the one below.
</p>
<source><![CDATA[
@@ -129,7 +148,7 @@
]]></source>
<p>
-9. Import statements must be fully qualified for clarity.
+10. Import statements must be fully qualified for clarity.
</p>
<source><![CDATA[
@@ -150,6 +169,68 @@
import org.apache.bar.*;
]]></source>
+<p>
+11. Import statements should be listed in alphabetical order. Use blank lines
+to seperate products. In cases where there is a large number of imports from a
+simple product (like java.x) consider seperating at the second level. For example,
+you could group all of the java.util, java.swing, etc...
+</p>
+
+<p>
+12. The conditional part of if and while statements should not use
+the equality operator for testing true or false values.
+</p>
+
+<source test=""><![CDATA[
+if (foo)
+
+and not
+
+if (foo==true)
+]]></source>
+
+<p>
+13. Always use the short form of the classname in code. Certain exception
+do apply where the fully qualified classname is required such as when
+java.sql.Date and java.util.Date are used in the same class. Otherwise, you
+should always import the class and use the short name.
+</p>
+
+<source test=""><![CDATA[
+try
+{
+}
+catch (IOException e)
+{
+}
+
+and not
+
+try
+{
+}
+catch (java.io.IOException e)
+{
+}
+]]></source>
+
+<p>
+14. Avoid using Iterators that are initialized outside of the loop.
+</p>
+
+<source test=""><![CDATA[
+for (Iterator iter=getIterator(); iter.hasNext; )
+{
+}
+
+and not
+
+Iterator iter=getIterator();
+for (;iter.hasNext; )
+{
+}
+]]></source>
+
<hr noshade="true" size="1"/>
<p>
@@ -181,6 +262,7 @@
<p>
Thanks for your cooperation.
</p>
+
</section>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
