qpid-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Qpid > Java Coding Standards
Date Wed, 05 Jun 2013 15:54:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/2042/9/21/_/styles/combined.css?spaceKey=qpid&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/qpid/Java+Coding+Standards">Java
Coding Standards</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~phil@philharveyonline.com">Phil
Harvey</a>
    </h4>
        <br/>
                         <h4>Changes (8)</h4>
                                 
    
<div id="page-diffs">
                    <table class="diff" cellpadding="0" cellspacing="0">
    
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >    System.out.println(&quot;Hello&quot;);
<br>{code} <br></td></tr>
            <tr><td class="diff-changed-lines" >* Fields prefixed with underscores,
e.g. <span class="diff-changed-words"><span class="diff-added-chars"style="background-color:
#dfd;">\</span>_messageCount</span> <br></td></tr>
            <tr><td class="diff-unchanged" >* Spaces after keywords but no spaces
either before or after parentheses in method calls, e.g. <br>{code} <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >This section gives guidelines for
class and interface definitions in Java. The term class in this section is used more broadly
to mean class and interface: <br># Class names should start with a capital letter with
every subsequent word capitalised, for example: DataProcessor \[mandatory\]. <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">#
All classes should be preceded by a javadoc comment describing the purpose of the class \[recommended\].
<br># Class-level javadoc comments should specify the thread-safety of the class \[recommended\].
<br></td></tr>
            <tr><td class="diff-unchanged" ># The name of exception classes should
end in the word exception, for example: UnknownMungeException \[mandatory\]. <br># Class
names should in general not be overloaded. For example, defining a class &quot;com.foo.bar.String&quot;
should be avoided as there is already a class &quot;java.lang.String&quot; \[recommended\].
<br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" ># Only one variable may be defined
per line \[mandatory\]. <br># Variable declarations should be indented 4 spaces more
than their enclosing class \[mandatory\]. <br></td></tr>
            <tr><td class="diff-changed-lines" ># All variables should be preceded
by a javadoc comment that specifies what the variable is for, where it is used and so forth.
The comment should be of the following form and be indented to the same level as the variable
it refers to <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">\[mandatory\]</span>
<span class="diff-added-words"style="background-color: #dfd;">\[recommended\]</span>
<br></td></tr>
            <tr><td class="diff-unchanged" ># Never declare instance variables
as public unless the class is effectively a &quot;struct&quot; \[mandatory\]. <br>#
Never give a variable the same name as a variable in a superclass \[mandatory\]. <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >Exceptions should be used to report
any failure to get or set a value. The &quot;@param&quot; description should detail
any assumptions made by the implementation, for example: &quot;Specifying a null value
will cause an error to be reported&quot;. <br># Method definitions should be indented
4 spaces more than their enclosing class \[mandatory\]. <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">#
All methods should be preceded by a javadoc comment specifying what the method is for, detailing
all arguments, returns and possible exceptions. This comment should be of the following form
and be indented to the same level as the method it refers to \[mandatory\]: <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">#
All non-private methods should be preceded by a javadoc comment specifying what the method
is for, detailing all arguments, returns and possible exceptions \[mandatory\] <br></td></tr>
            <tr><td class="diff-unchanged" ># The braces associated with a method
should be on a line on their own and be indented to the same level as the method \[mandatory\].
For example: <br>{code} <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >This section defines the rules to
be used for Java expressions: <br># Unary operators should not be separated from their
operand by white space \[mandatory\]. <br></td></tr>
            <tr><td class="diff-changed-lines" ># Embedded <span class="diff-changed-words"><span
class="diff-added-chars"style="background-color: #dfd;">\</span>+<span class="diff-added-chars"style="background-color:
#dfd;">\</span>+</span> or -- operators should only be used when it improves
code clarity \[recommended\]. This is rare. <br></td></tr>
            <tr><td class="diff-unchanged" ># Extra parenthesis should be used
in expressions to improve their clarity \[recommended\]. <br># The logical expression
operand of the &quot;?:&quot; (ternary) operator must be enclosed in parenthesis.
If the other operands are also expressions then they should also be enclosed in parenthesis
\[mandatory\]. For example: <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >} <br>{code} <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">#
To indicate that further work is intended on a section of code, add a comment prefixed by
&quot;TODO&quot; explaining what needs to be done and why \[recommended\]. <br>#
If code is so incomplete that executing it would lead to incorrect or confusing results, throw
UnsupportedOperationException with an explanatory message \[mandatory\]. <br> <br></td></tr>
            <tr><td class="diff-unchanged" >h4. Exceptions <br> <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >} <br>{code} <br></td></tr>
            <tr><td class="diff-changed-lines" >4.	When an exception is caught
but ignored then a comment should be supplied explaining the rationale <span class="diff-added-words"style="background-color:
#dfd;">(note that this rule includes InterruptedException, which should almost never be
ignored)</span> \[mandatory\]. For example: <br></td></tr>
            <tr><td class="diff-unchanged" >{code} <br>try <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <p>This page documents the standard adopted for Java code in the Qpid project.
All committers are expected to follow these standards; checkstyle or similar is used to check
compliance.</p>

<div>
<ul>
    <li><a href='#JavaCodingStandards-ExecutiveSummary'>Executive Summary</a></li>
    <li><a href='#JavaCodingStandards-Details'>Details</a></li>
<ul>
    <li><a href='#JavaCodingStandards-Introduction'>Introduction</a></li>
    <li><a href='#JavaCodingStandards-Sourcefiles'>Source files</a></li>
</ul>
    <li><a href='#JavaCodingStandards-JavaElements'>Java Elements</a></li>
<ul>
    <li><a href='#JavaCodingStandards-Classdefinitions'>Class definitions</a></li>
    <li><a href='#JavaCodingStandards-Variables'>Variables</a></li>
    <li><a href='#JavaCodingStandards-Methods'>Methods</a></li>
    <li><a href='#JavaCodingStandards-Expressions'>Expressions</a></li>
    <li><a href='#JavaCodingStandards-Statements'>Statements</a></li>
<ul>
    <li><a href='#JavaCodingStandards-SimpleStatements'>Simple Statements</a></li>
    <li><a href='#JavaCodingStandards-CompoundStatements'>Compound Statements</a></li>
</ul>
    <li><a href='#JavaCodingStandards-General'>General</a></li>
    <li><a href='#JavaCodingStandards-Exceptions'>Exceptions</a></li>
</ul>
</ul></div>

<h3><a name="JavaCodingStandards-ExecutiveSummary"></a>Executive Summary</h3>

<p>The main things for layout purposes in the standard are:</p>

<ul>
	<li>Indent using four spaces. <b>No tabs</b>.</li>
	<li>braces always go on new lines, e.g.</li>
</ul>


<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">if</span> (x == 5)
{
    <span class="code-object">System</span>.out.println(<span class="code-quote">"Hello"</span>);
}
</pre>
</div></div>

<p>rather than</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">if</span> (x == 5} {
    <span class="code-object">System</span>.out.println(<span class="code-quote">"Hello"</span>);
}
</pre>
</div></div>
<ul>
	<li>Always add braces, e.g.
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">if</span> (x == 5)
{
    <span class="code-object">System</span>.out.println(<span class="code-quote">"Hello"</span>);
}
</pre>
</div></div></li>
</ul>


<p>rather than</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">if</span> (x == 5}
    <span class="code-object">System</span>.out.println(<span class="code-quote">"Hello"</span>);
</pre>
</div></div>
<ul>
	<li>Fields prefixed with underscores, e.g. &#95;messageCount</li>
	<li>Spaces after keywords but no spaces either before or after parentheses in method
calls, e.g.
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">if</span> (x == 5)
</pre>
</div></div>
<p>rather than</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">if</span>(x==5)
</pre>
</div></div>
<p>but</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
foo.bar(4, 5)
</pre>
</div></div>
<p>rather than</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
foo.bar( 4, 5 )
</pre>
</div></div></li>
</ul>


<h3><a name="JavaCodingStandards-Details"></a>Details</h3>

<h4><a name="JavaCodingStandards-Introduction"></a>Introduction</h4>

<p>This document describes two types of coding standard:</p>

<p>1. <b>Mandatory</b> standards must be followed at all times.<br/>
2. <b>Recommended</b> standards should in general be followed but in particular
cases may be omitted where the programmer feels that there is a good reason to do so.</p>

<p>Code that does not adhere to mandatory standards will not pass the automated checks
(or a code review if the guideline is not stylistic).</p>

<h4><a name="JavaCodingStandards-Sourcefiles"></a>Source files</h4>

<p>This section defines the general rules associated with the contents of a Java source
file and the order in which the each part should be presented. No rules on programming style,
naming conventions or indentation are given here.</p>

<ol>
	<li>Java source files must have a ".java" suffix (this will be enforced by the compiler)
[mandatory].</li>
	<li>The basename of a Java source file must be the same as the public class defined
therein (this will be enforced by the compiler) [mandatory].</li>
	<li>Only one class should be defined per source file (except for inner classes and
one-shot uses where the non-public class cannot conceivably be used outside of its context)
[mandatory].</li>
	<li>Source files should not exceed 1500 lines [recommended].</li>
	<li>No line in a source file should exceed 120 characters [mandatory].</li>
	<li>The sections of a source file should be presented in the following order [mandatory]:</li>
</ol>


<ul>
	<li>File information comment (see rule 7 below).</li>
	<li>Package name (see rules 1 to 3 in the section 2.1 above and rule 8 below).</li>
	<li>Imports (see rules 9 to 10 below).</li>
	<li>Other class definitions.</li>
	<li>Public class definition.</li>
</ul>


<ol>
	<li>Do not use automatically expanded log or revision number provided by your source
code management system unless it provides a facility to avoid "false conflicts" when doing
merges due simply to revision number changes (which happens, for example, with cvs when branches
are used). [mandatory]</li>
	<li>Every class that is to be released must be a member of a package [mandatory].<br/>
Rationale: classes that are not explicitly put in a package are placed in the unnamed package
by the compiler. Therefore as the classes from many developers will be being placed in the
same package the likelihood of a name clash is greatly increased.</li>
	<li>All class imports from the same package should be grouped together. A single blank
line should separate imports from different packages [recommended].</li>
	<li>Use javadoc tags and use HTML mark-up to enhance the readability of the output
files [mandatory].</li>
</ol>


<h3><a name="JavaCodingStandards-JavaElements"></a>Java Elements</h3>

<p>This section gives advice on coding the various elements of the Java programming
language.</p>

<h4><a name="JavaCodingStandards-Classdefinitions"></a>Class definitions</h4>

<p>This section gives guidelines for class and interface definitions in Java. The term
class in this section is used more broadly to mean class and interface:</p>
<ol>
	<li>Class names should start with a capital letter with every subsequent word capitalised,
for example: DataProcessor [mandatory].</li>
	<li>All classes should be preceded by a javadoc comment describing the purpose of the
class [recommended].</li>
	<li>Class-level javadoc comments should specify the thread-safety of the class [recommended].</li>
	<li>The name of exception classes should end in the word exception, for example: UnknownMungeException
[mandatory].</li>
	<li>Class names should in general not be overloaded. For example, defining a class
"com.foo.bar.String" should be avoided as there is already a class "java.lang.String" [recommended].<br/>
Rationale: adhering to this rule reduces the likelihood of confusion and means that the use
of fully qualified class names should not be required.</li>
	<li>The definition of the primary class (i.e. the class with the same name as the java
file) should start in column 0 of the source file. Inner class definitions should be indented
4 spaces more than their enclosing class [mandatory].</li>
	<li>Declare a class as final only if specialisation will never be required and improved
performance is essential. With modern JVMs there in fact may be no performance advantage.
Warning: use of final limits code reuse [mandatory].</li>
	<li>For all but simplest classes the following methods should have useful definitions
[recommended]:
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">public</span> <span class="code-object">boolean</span>
equals(<span class="code-object">Object</span> obj)
<span class="code-keyword">public</span> <span class="code-object">int</span>
hashCode()
<span class="code-keyword">public</span> <span class="code-object">String</span>
toString()
</pre>
</div></div></li>
	<li>The order of presentation of the sections in a class should be [mandatory]:</li>
</ol>


<ul>
	<li>Variables</li>
	<li>Methods
<h4><a name="JavaCodingStandards-Variables"></a>Variables</h4>
<p>This section gives guidelines for class and instance variable definitions in Java.
In this section if a rule uses the term variable rather than instance variable or class variable,
then the rule applies to both types of variable.</p></li>
</ul>


<ol>
	<li>The order of presentation of variables in a class definition should be [recommended]:</li>
</ol>


<ul>
	<li>private, protected, public: static final variables (aka constant class variables).</li>
	<li>private, protected, public: static variables (aka class variables).</li>
	<li>private, protected, public: final variables (aka constant instance variables).</li>
	<li>private, protected, public: variables (aka instance variables).<br/>
It should be noted that as javadoc will automatically order variables in a consistent manner,
rigid adherence to this rule is not necessary.</li>
</ul>


<ol>
	<li>Variable modifiers should be presented in the following order: static, final, transient,
volatile [mandatory].</li>
	<li>The names of static final variables should be upper case with subsequent words
prefixed with an underscore [mandatory]. For example:
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">public</span> <span class="code-keyword">static</span>
<span class="code-keyword">final</span> <span class="code-object">int</span>
NOT_FOUND = -1;
</pre>
</div></div></li>
	<li>When a subclass refers to a static final variable defined in a parent class, access
should be qualified by specifying the defining class name [mandatory]. For example: use ParentClass.MAX
rather than MAX.</li>
	<li>The names of variables (other that static final) should start with a lower case
letter. Any words that are contained in the rest of the variable name should be capitalised
[mandatory]. For example:
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-object">String</span> name;
<span class="code-object">String</span>[] childrensNames;
</pre>
</div></div></li>
	<li>Class and instance variables must be prefixed with an underscore (_) [mandatory].</li>
	<li>Variables must not be named using the so-called Hungarian notation [mandatory].
For example:
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-object">int</span> nCount = 4; <span class="code-comment">//
not allowed</span>
</pre>
</div></div></li>
	<li>Only one variable may be defined per line [mandatory].</li>
	<li>Variable declarations should be indented 4 spaces more than their enclosing class
[mandatory].</li>
	<li>All variables should be preceded by a javadoc comment that specifies what the variable
is for, where it is used and so forth. The comment should be of the following form and be
indented to the same level as the variable it refers to [recommended]</li>
	<li>Never declare instance variables as public unless the class is effectively a "struct"
[mandatory].</li>
	<li>Never give a variable the same name as a variable in a superclass [mandatory].</li>
	<li>Ensure that all non-private class variables have sensible values even if no instances
have been created (use static initialisers if necessary, i.e. "static { ... }") [mandatory].<br/>
Rationale: prevents other objects accessing fields with undefined/unexpected values.
<h4><a name="JavaCodingStandards-Methods"></a>Methods</h4>
<p>This section gives guidelines for class and instance method definitions in Java.
In this section if a rule uses the term method rather than instance method or class method,
then the rule applies to both types of method.</p></li>
	<li>Constructors and finalize methods should follow immediately after the variable
declarations [mandatory].</li>
	<li>Do not call non-final methods from constructors. This can lead to unexpected results
when the class is subclassed. If you must call non-final methods from constructors, document
this in the constructor's javadoc [mandatory]. Note that private implies final.</li>
	<li>Methods that are associated with the same area of functionality should be physically
close to one another [recommended].</li>
	<li>After grouping by functionality, methods should be presented in the following order
[recommended]:</li>
</ol>


<ul>
	<li>private, protected, public: static methods.</li>
	<li>private, protected, public: instance methods.<br/>
It should be noted that as javadoc will automatically order methods in a consistent manner,
rigid adherence to this rule is not necessary.</li>
</ul>


<ol>
	<li>Method modifiers should be presented in the following order: abstract, static,
final., synchronized [mandatory]</li>
	<li>When a synchronized method is overloaded, it should be explicitly synchronized
in the subclass [recommended].</li>
	<li>Method names should start with a lower case letter with all subsequent words being
capitalised [mandatory]. For example:
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">protected</span> <span class="code-object">int</span>
resize(<span class="code-object">int</span> newSize)
<span class="code-keyword">protected</span> void addContentsTo(Container destinationContainer)
</pre>
</div></div></li>
	<li>Methods which get and set values should be named as follows [mandatory]:
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
Type getVariableName()
void setVariableName(Type newValue)
</pre>
</div></div>
<p>Exceptions should be used to report any failure to get or set a value. The "@param"
description should detail any assumptions made by the implementation, for example: "Specifying
a null value will cause an error to be reported".</p></li>
	<li>Method definitions should be indented 4 spaces more than their enclosing class
[mandatory].</li>
	<li>All non-private methods should be preceded by a javadoc comment specifying what
the method is for, detailing all arguments, returns and possible exceptions [mandatory]</li>
	<li>The braces associated with a method should be on a line on their own and be indented
to the same level as the method [mandatory]. For example:
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">public</span> void munge()
{
    <span class="code-object">int</span> i;
    <span class="code-comment">// method definition omitted...
</span>}
</pre>
</div></div></li>
	<li>The body of a method should be indented 4 columns further that the opening and
closing braces associated with it [mandatory]. See the above rule for an example.</li>
	<li>When declaring and calling methods there should be no white space before or after
the parenthesis [mandatory].</li>
	<li>In argument lists there should be no white space before a comma, and only a single
space (or newline) after it [mandatory]. For example:
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">public</span> void munge(<span class="code-object">int</span>
depth, <span class="code-object">String</span> name)
{
    <span class="code-keyword">if</span> (depth &gt; 0)
    {
        munge(depth - 1, name);
    }
    <span class="code-comment">// <span class="code-keyword">do</span> something
</span>}
</pre>
</div></div></li>
	<li>Wherever reasonable define a default constructor (i.e. one that takes no arguments)
so that Class.newInstance() may be used [recommended]. If an instance which was created by
default construction could be used until further initialisation has been performed, then all
unserviceable requests should cause a runtime exception to be thrown.</li>
	<li>The method public static void main() should not be used for test purposes. Instead
a test/demo program should be supplied separately. [mandatory].</li>
	<li>Public access methods (i.e. methods that get and set attributes) should only be
supplied when required [mandatory].</li>
	<li>If an instance method has no natural return value, declare it as void rather than
using the "return this;" convention [mandatory].</li>
	<li>Ensure that non-private static methods behave sensibly if no instances of the defining
class have been created [mandatory].
<h4><a name="JavaCodingStandards-Expressions"></a>Expressions</h4>
<p>This section defines the rules to be used for Java expressions:</p></li>
	<li>Unary operators should not be separated from their operand by white space [mandatory].</li>
	<li>Embedded &#43;&#43; or &#8211; operators should only be used when it
improves code clarity [recommended]. This is rare.</li>
	<li>Extra parenthesis should be used in expressions to improve their clarity [recommended].</li>
	<li>The logical expression operand of the "?:" (ternary) operator must be enclosed
in parenthesis. If the other operands are also expressions then they should also be enclosed
in parenthesis [mandatory]. For example:
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
biggest = (a &gt; b) ? a : b;
complex = (a + b &gt; 100) ? (100 * c) : (10 * d);
</pre>
</div></div></li>
	<li>Nested "?:" (ternary) operators can be confusing and should be avoided [mandatory].</li>
	<li>Use of the binary "," operator (the comma operator) should be avoided [mandatory].
Putting all the work of a for loop on a single line is not a sign of great wisdom and talent.</li>
	<li>If an expression is too long for a line (i.e. extends beyond column 119) then it
should be split after the lowest precedence operator near the break [mandatory]. For example:
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">if</span> ((state == NEED_TO_REPLY) ||
    (state == REPLY_ACK_TIMEOUT))
{
    <span class="code-comment">// (re)send the reply and enter state WAITING_FOR_REPLY_ACK
</span>}
</pre>
</div></div>
<p>Furthermore if an expression requires to be split more than once, then the split
should occur at the same logical level if possible.</p></li>
	<li>All binary and ternary operators (exception for ".") should be separated from their
operands by a space [mandatory].
<h4><a name="JavaCodingStandards-Statements"></a>Statements</h4></li>
</ol>



<h5><a name="JavaCodingStandards-SimpleStatements"></a>Simple Statements</h5>

<p>This section defines the general rules for simple Java statements:</p>
<ol>
	<li>There must only be one statement per line [mandatory].</li>
	<li>In general local variables should be named in a similar manner to instance variables
[recommended].</li>
	<li>More than one temporary variable may be declared on a single line provided no initialisers
are used [mandatory]. For example:
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-object">int</span> j, k = 10, l;  <span class="code-comment">//
Incorrect!
</span><span class="code-object">int</span> j, l;          <span class="code-comment">//
Correct
</span><span class="code-object">int</span> k = 10;
</pre>
</div></div></li>
	<li>A null body for a while, for, if, etc. should be documented so that it is clearly
intentional [mandatory].</li>
	<li>Keywords that are followed by a parenthesised expression (such as while, if, etc)
should be separated from the open bracket by a single space [mandatory]. For example:
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">if</span> (a &gt; b)
{
    munge();
}
</pre>
</div></div></li>
	<li>In method calls, there should be no spaces before or after the parentheses [mandatory].
For example:
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
munge (a, 10);    <span class="code-comment">// Incorrect!
</span>munge(a, 10);     <span class="code-comment">// Correct.</span>
</pre>
</div></div></li>
</ol>


<h5><a name="JavaCodingStandards-CompoundStatements"></a>Compound Statements</h5>

<p>This section defines the general rules associated with compound statements in Java:</p>
<ol>
	<li>The body of a compound statement should be indented by 4 spaces more than the enclosing
braces [mandatory]. See the following rule for an example.</li>
	<li>The braces associated with a compound statement should be on their own line and
be indented to the same level as the surrounding code [mandatory]. For example:
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">if</span> ((length &gt;= LEN_BOX) &amp;&amp;
(width &gt;= WID_BOX))
{
    <span class="code-object">int</span> i;
    <span class="code-comment">// Statements omitted...
</span>}
</pre>
</div></div></li>
	<li>If the opening and closing braces associated with a compound statement are further
than 20 lines apart then the closing brace should annotated as follows [mandatory]:
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">for</span> (<span class="code-object">int</span>
j = 0; j &lt; SIZE; j++)
{
    lotsOfCode();
} <span class="code-comment">// end <span class="code-keyword">for</span></span>
</pre>
</div></div></li>
	<li>All statements associated with an  if or if-else statement should be made compound
by the use of braces [mandatory]. For example:
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">if</span> (a &gt; b)
{
    statement();
}
<span class="code-keyword">else</span>
{
    statement1();
    statement2();
}
</pre>
</div></div></li>
	<li>The case labels in a switch statement should be on their own line and indented
by a further 4 spaces. The statements associated with the label should be indented by 4 columns
more than the label and not be enclosed in a compound statement. [mandatory]. For example:
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">switch</span> (tState)
{
    <span class="code-keyword">case</span> NOT_RUNNING:
        start();
        <span class="code-keyword">break</span>;

    <span class="code-keyword">case</span> RUNNING:
    <span class="code-keyword">default</span>:
        monitor();
        <span class="code-keyword">break</span>;
}
</pre>
</div></div></li>
	<li>In switch statements - the statements associated with all cases should terminate
with a statement which explicitly determines the flow of control, for example break [recommended].</li>
	<li>In switch statements - fall through should be avoided wherever possible, however
if it is unavoidable it must be commented with "// FALLTHROUGH" [mandatory].</li>
	<li>In switch statements - a default case must be present and should always be the
last case [mandatory].
<h4><a name="JavaCodingStandards-General"></a>General</h4>
<p>This section gives general rules to be followed when programming in Java:</p></li>
	<li>When comparing objects for equivalence use the method equals() and not the == operator.
The only exceptions to this are static final objects that are being used as constants and
interned Strings [mandatory].</li>
	<li>In general labelled break and continue statements should be avoided [recommended].
This is due to the complex flow of control, especially when used with try/finally blocks.</li>
	<li>Unless some aspect of an algorithm relies on it, then loops count forward [mandatory].
For example:
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">for</span> (<span class="code-object">int</span>
j = 0; j &lt; size; j++)
{
    <span class="code-comment">// Do something interesting
</span>}
</pre>
</div></div></li>
	<li>Use local variables in loops [recommended]. For example:
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
ArrayList clone = (ArrayList)listeners.clone();
<span class="code-keyword">final</span> <span class="code-object">int</span>
size = clone.size();
<span class="code-keyword">for</span> (<span class="code-object">int</span>
j = 0; j &lt; size; j++)
{
    <span class="code-object">System</span>.out.println(clone.elementAt(j));
}
</pre>
</div></div></li>
	<li>Anonymous inner classes should define no instance variables and be limited to three
single line methods. Inner classes that declare instance variables or have more complex methods
should be named [mandatory].</li>
	<li>Use final local variables where possible to help avoid errors in code [recommended].
For example:
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">public</span> void foo()
{
    <span class="code-keyword">final</span> <span class="code-object">int</span>
x = dataSource.getCount();
    <span class="code-comment">// <span class="code-keyword">do</span> things
with x
</span>    <span class="code-comment">// ...
</span>}
</pre>
</div></div></li>
	<li>To indicate that further work is intended on a section of code, add a comment prefixed
by "TODO" explaining what needs to be done and why [recommended].</li>
	<li>If code is so incomplete that executing it would lead to incorrect or confusing
results, throw UnsupportedOperationException with an explanatory message [mandatory].</li>
</ol>


<h4><a name="JavaCodingStandards-Exceptions"></a>Exceptions</h4>

<p>This section gives general guidance on the use of exceptions when programming in
Java.</p>
<ol>
	<li>try/catch blocks should be laid out like any other compound statement [mandatory].
For example:
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">try</span>
{
    <span class="code-object">String</span> str = someStrings[specifiedIndex];
}
<span class="code-keyword">catch</span> (IndexOutOfBoundsException ex)
{
    <span class="code-comment">// The user specified an incorrect index, better take
</span>    <span class="code-comment">// some remedial action.
</span>}
</pre>
</div></div>
<p>4.	When an exception is caught but ignored then a comment should be supplied explaining
the rationale (note that this rule includes InterruptedException, which should almost never
be ignored) [mandatory]. For example:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">try</span>
{
    propertySet.setProperty(<span class="code-quote">"thingy"</span>, <span
class="code-keyword">new</span> <span class="code-object">Integer</span>(10));
}
<span class="code-keyword">catch</span> (UnknownPropertyException ignore)
{
    <span class="code-comment">// This exception will never occur as <span class="code-quote">"thingy"</span>
definitely exists
</span>}
</pre>
</div></div></li>
	<li>All exceptions that are likely to be thrown by a method should be documented, except
if they are runtime exceptions (note: the compiler will not enforce catch blocks for runtimes
even if they are mentioned in the throws clause) [mandatory]. For example:
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
/* Comment snippet:
 * @exception IllegalValueException Thrown <span class="code-keyword">if</span>
values is <span class="code-keyword">null</span> or
 *     any of the integers it contains is <span class="code-keyword">null</span>.
 */
<span class="code-keyword">private</span> <span class="code-object">Integer</span>
sum(<span class="code-object">Integer</span>[] values) <span class="code-keyword">throws</span>
IllegalValueException
</pre>
</div></div></li>
</ol>

    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/qpid/Java+Coding+Standards">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=28247&revisedVersion=11&originalVersion=10">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/qpid/Java+Coding+Standards?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org


Mime
View raw message