ace-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r813629 - in /websites/staging/ace/trunk/content: ./ dev-doc/coding-standards.html
Date Thu, 19 Apr 2012 09:17:31 GMT
Author: buildbot
Date: Thu Apr 19 09:17:30 2012
New Revision: 813629

Log:
Staging update by buildbot for ace

Modified:
    websites/staging/ace/trunk/content/   (props changed)
    websites/staging/ace/trunk/content/dev-doc/coding-standards.html

Propchange: websites/staging/ace/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Thu Apr 19 09:17:30 2012
@@ -1 +1 @@
-1327872
+1327884

Modified: websites/staging/ace/trunk/content/dev-doc/coding-standards.html
==============================================================================
--- websites/staging/ace/trunk/content/dev-doc/coding-standards.html (original)
+++ websites/staging/ace/trunk/content/dev-doc/coding-standards.html Thu Apr 19 09:17:30 2012
@@ -153,6 +153,69 @@
       <h1>Coding Standards</h1>
       <div class="clear"></div>
       <div id="content"><p>This is a Java coding style guide for the Apache ACE project.</p>
+<div class="toc">
+<ul>
+<li><a href="#summary">Summary</a></li>
+<li><a href="#class-layout-and-comments">Class layout and comments</a><ul>
+<li><a href="#files-and-filenames">Files and filenames</a><ul>
+<li><a href="#file-names">File names</a></li>
+<li><a href="#file-organization">File organization</a></li>
+<li><a href="#beginning-comments">Beginning comments</a><ul>
+<li><a href="#package-and-import-statements">Package and import statements</a></li>
+<li><a href="#class-interface-enum-and-annotation-declarations">Class, interface, enum and annotation declarations</a></li>
+<li><a href="#annotations">Annotations</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a href="#indentation">Indentation</a><ul>
+<li><a href="#line-length">Line length</a></li>
+<li><a href="#wrapping-lines">Wrapping lines</a></li>
+</ul>
+</li>
+<li><a href="#comment">Comment</a><ul>
+<li><a href="#comment-styles">Comment styles</a><ul>
+<li><a href="#single-line-comments">Single line comments</a></li>
+<li><a href="#block-comments">Block comments</a></li>
+<li><a href="#javadoc-comments">JavaDoc comments</a><ul>
+<li><a href="#html-tags">HTML tags</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a href="#java-syntax-and-its-layout">Java syntax and its layout</a><ul>
+<li><a href="#declarations">Declarations</a><ul>
+<li><a href="#number-per-line">Number per line</a></li>
+<li><a href="#placement">Placement</a></li>
+<li><a href="#initialization">Initialization</a></li>
+<li><a href="#class-and-interface-declarations">Class and Interface Declarations</a></li>
+</ul>
+</li>
+<li><a href="#statements">Statements</a><ul>
+<li><a href="#simple-statements">Simple statements</a></li>
+<li><a href="#compound-statements">Compound statements</a></li>
+<li><a href="#if-if-else-if-else-if-else-statements">if, if-else, if else-if else statements</a></li>
+<li><a href="#switch">switch</a></li>
+<li><a href="#try-catch">try - catch</a></li>
+<li><a href="#for-loops">for loops</a></li>
+</ul>
+</li>
+<li><a href="#white-space">White Space</a><ul>
+<li><a href="#blank-lines">Blank lines</a></li>
+<li><a href="#blank-spaces">Blank spaces</a></li>
+</ul>
+</li>
+<li><a href="#namingconventions">Naming conventions</a></li>
+</ul>
+</li>
+<li><a href="#downloads">Downloads</a></li>
+<li><a href="#references">References</a></li>
+</ul>
+</div>
 <h2 id="summary">Summary</h2>
 <p>This style guide is intended to help the computer professional produce better Java programs. It presents a set of specific guidelines for using the features of Java in a disciplined manner. The goal is to develop high quality, reliable, reusable, portable software. For a number of reasons, no programming language can ensure the achievements of these desirable objectives on its own. Programming must be embedded in a disciplined development process that addresses a number of topics in a well managed way. The use of Java is one of those. It must conform to good programming practice based on well established software engineering principles. This style guide is intended to bridge the gap between these principles and the actual practice of programming in Java.</p>
 <p>Clear, readable, understandable source text eases program evolution, adaptation and maintenance. First, such source text is more likely to be correct and reliable. Second, effective code adaptation is a prerequisite to code reuse, a technique that has the potential for drastic reductions in system development costs. Easy adaptation requires thorough understanding of the software, and that is facilitated considerably by clarity. Finally, since maintenance (really evolution) is a costly process that continues throughout the life of a system, clarity plays a major role in keeping maintenance costs down. Over the entire life cycle, code has to be read and understood far more often than it is written; the investment of effort in writing readable, understandable code is thus well worthwhile. Many of the guidelines in this style guide are designed to promote clarity of the source text.</p>
@@ -175,26 +238,26 @@
 <p>Beginning comments are used for licensing and copyright information only. Here at Apache, we embed the ASL 2.0 headers at the top of every file. Note that they are not according to the JavaDoc style (See: How to write doc comments for JavaDoc - Sun Microsystems, Inc.).</p>
 <h5 id="package-and-import-statements">Package and import statements</h5>
 <p>The first non-comment line of most Java source files is a package statement. After an empty line import statements can follow. For example:</p>
-<div class="codehilite"><pre><span class="nb">package</span> <span class="n">org</span><span class="o">.</span><span class="n">apache</span><span class="o">.</span><span class="n">ace</span><span class="o">.</span><span class="n">core</span><span class="o">.</span><span class="n">ui</span><span class="p">;</span>
+<div class="codehilite"><pre><span class="kn">package</span> <span class="n">org</span><span class="o">.</span><span class="na">apache</span><span class="o">.</span><span class="na">ace</span><span class="o">.</span><span class="na">core</span><span class="o">.</span><span class="na">ui</span><span class="o">;</span>
 
-<span class="nb">import</span> <span class="n">java</span><span class="o">.</span><span class="n">awt</span><span class="o">.</span><span class="n">Frame</span><span class="p">;</span>
-<span class="nb">import</span> <span class="n">java</span><span class="o">.</span><span class="n">io</span><span class="o">.</span><span class="n">InputStream</span><span class="p">;</span>
+<span class="kn">import</span> <span class="nn">java.awt.Frame</span><span class="o">;</span>
+<span class="kn">import</span> <span class="nn">java.io.InputStream</span><span class="o">;</span>
 </pre></div>
 
 
 <p>A few notes must be made here:</p>
 <ol>
-<li><em>Package rules.</em> When not using an explicit package statement in your code the code still is in a package, the default package. This easily results in name clashes and as package naming should be a part of the design, always use an explicit package name. For naming rules of packages see [naming conventions|#namingconventions].</li>
-<li><em>Import statements</em> need to be explicit in order to overcome name clashes. They must be grouped by name.</li>
+<li><em>Package rules.</em> When not using an explicit package statement in your code the code still is in a package, the default package. This easily results in name clashes and as package naming should be a part of the design, always use an explicit package name. For naming rules of packages see <a href="#namingconventions">naming conventions</a>;</li>
+<li><em>Import statements</em> need to be explicit in order to overcome name clashes. They must be grouped by name;</li>
 <li><em>Import order.</em> First in this section should be the standard Java imports like: java.lang.Throwable. Second should be the Java extensions (i.e. javax), third, the third party stuff. Finally the project-specific imports should be added.</li>
 </ol>
 <h5 id="class-interface-enum-and-annotation-declarations">Class, interface, enum and annotation declarations</h5>
 <p>The following comment block is an example for the comment that belongs to the declaration of a class, interface, enum or annotation. The JavaDoc syntax results in the following block:</p>
-<div class="codehilite"><pre><span class="o">/**</span>
- <span class="o">*</span> <span class="n">Configuration</span> <span class="n">manager</span><span class="o">.</span> <span class="n">Manages</span> <span class="n">the</span> <span class="n">configuration</span> <span class="n">of</span> <span class="n">an</span> <span class="n">application</span><span class="o">.</span> <span class="n">Has</span> <span class="n">features</span>
- <span class="o">*</span> <span class="n">to</span> <span class="nb">import</span> <span class="ow">and</span> <span class="n">export</span> <span class="n">whole</span> <span class="n">configurations</span> <span class="ow">and</span> <span class="n">notifies</span> <span class="n">components</span> <span class="n">that</span> <span class="n">need</span> <span class="n">to</span>
- <span class="o">*</span> <span class="n">receive</span> <span class="n">settings</span><span class="o">.</span>
- <span class="o">*/</span>
+<div class="codehilite"><pre><span class="cm">/**</span>
+<span class="cm"> * Configuration manager. Manages the configuration of an application. Has features</span>
+<span class="cm"> * to import and export whole configurations and notifies components that need to</span>
+<span class="cm"> * receive settings.</span>
+<span class="cm"> */</span>
 </pre></div>
 
 
@@ -239,22 +302,22 @@
 </table>
 <h5 id="annotations">Annotations</h5>
 <p>Annotations for classes and methods should be done on the line directly above the class or method. They should be indented to the same level. An example:</p>
-<div class="codehilite"><pre><span class="nv">@Manageable</span><span class="p">(</span><span class="n">description</span> <span class="o">=</span> <span class="s">&quot;Starts the system.&quot;</span><span class="p">)</span>
-<span class="n">public</span> <span class="n">void</span> <span class="n">start</span><span class="p">()</span> <span class="p">{</span>
-    <span class="sr">//</span> <span class="o">...</span>
-<span class="p">}</span>
+<div class="codehilite"><pre><span class="nd">@Manageable</span><span class="o">(</span><span class="n">description</span> <span class="o">=</span> <span class="s">&quot;Starts the system.&quot;</span><span class="o">)</span>
+<span class="kd">public</span> <span class="kt">void</span> <span class="nf">start</span><span class="o">()</span> <span class="o">{</span>
+    <span class="c1">// ...</span>
+<span class="o">}</span>
 </pre></div>
 
 
 <p>Annotations for parameters can be inlined like this:</p>
-<div class="codehilite"><pre><span class="n">public</span> <span class="n">void</span> <span class="n">setValue</span><span class="p">(</span><span class="nv">@Validation</span><span class="p">(</span><span class="s">&quot;x &gt; 0 &amp;&amp; x &lt; 10&quot;</span><span class="p">,</span> <span class="s">&quot;Should be between 0 and 10.&quot;</span><span class="p">)</span> <span class="nb">int</span> <span class="n">x</span><span class="p">)</span> <span class="p">{</span>
-    <span class="sr">//</span> <span class="o">...</span>
-<span class="p">}</span>
+<div class="codehilite"><pre><span class="kd">public</span> <span class="kt">void</span> <span class="nf">setValue</span><span class="o">(</span><span class="nd">@Validation</span><span class="o">(</span><span class="s">&quot;x &gt; 0 &amp;&amp; x &lt; 10&quot;</span><span class="o">,</span> <span class="s">&quot;Should be between 0 and 10.&quot;</span><span class="o">)</span> <span class="kt">int</span> <span class="n">x</span><span class="o">)</span> <span class="o">{</span>
+    <span class="c1">// ...</span>
+<span class="o">}</span>
 </pre></div>
 
 
 <h3 id="indentation">Indentation</h3>
-<p>Four spaces should be used as unit of indentation. Use spaces or let your editor convert tabs to spaces as some editors might show the tabs different than they were intended! Tabs must be set exactly every 4 spaces.</p>
+<p>Four spaces should be used as unit of indentation. Use spaces or let your editor convert tabs to spaces as some editors might show the tabs different than they were intended! Tabs <em>must</em> be set <em>exactly</em> every 4 spaces.</p>
 <h4 id="line-length">Line length</h4>
 <p>There is no explicit limit for the length of a line. Make sure that the flow of the code is clear and that, when printing the file, it is well formed when using a reasonable font.</p>
 <h4 id="wrapping-lines">Wrapping lines</h4>
@@ -275,39 +338,39 @@
 <li>JavaDoc comments.</li>
 </ol>
 <h5 id="single-line-comments">Single line comments</h5>
-<p>The compiler ignores everything from // to the end of the line. Use this style when adding a description or some kind of explanation on the same line of code or the line above.</p>
-<div class="codehilite"><pre><span class="nb">int</span> <span class="n">a</span><span class="p">;</span> <span class="sr">//</span> <span class="n">acceleration</span> <span class="n">of</span> <span class="n">the</span> <span class="n">car</span>
+<p>The compiler ignores everything from <code>//</code> to the end of the line. Use this style when adding a description or some kind of explanation on the same line of code or the line above.</p>
+<div class="codehilite"><pre><span class="kt">int</span> <span class="n">a</span><span class="o">;</span> <span class="c1">// acceleration of the car</span>
 
-<span class="sr">//</span> <span class="n">all</span> <span class="n">names</span> <span class="n">that</span> <span class="n">should</span> <span class="n">be</span> <span class="n">searched</span>
-<span class="n">String</span><span class="o">[]</span> <span class="n">names</span><span class="p">;</span>
+<span class="c1">// all names that should be searched</span>
+<span class="n">String</span><span class="o">[]</span> <span class="n">names</span><span class="o">;</span>
 </pre></div>
 
 
 <h5 id="block-comments">Block comments</h5>
-<p>The compiler ignores everything from /<em> to </em>/. Use this style for internal comments and copyright headers.</p>
-<div class="codehilite"><pre><span class="o">/*</span>
- <span class="o">*</span> <span class="n">This</span> <span class="n">code</span> <span class="n">is</span> <span class="n">Copyright</span> <span class="p">(</span><span class="n">c</span><span class="p">)</span> <span class="mi">2012</span> <span class="n">Apache</span> <span class="n">Software</span> <span class="n">Foundation</span><span class="o">.</span> <span class="n">All</span> <span class="n">rights</span> <span class="n">reserved</span><span class="o">.</span>
- <span class="o">*</span> <span class="n">You</span> <span class="n">are</span> <span class="ow">not</span> <span class="n">allowed</span> <span class="n">to</span> <span class="n">remember</span> <span class="ow">or</span> <span class="n">reproduce</span> <span class="n">anything</span> <span class="n">you</span> <span class="nb">read</span> <span class="n">below</span><span class="o">.</span>
- <span class="o">*/</span>
+<p>The compiler ignores everything from <code>/*</code> to <code>*/</code>. Use this style for internal comments and copyright headers.</p>
+<div class="codehilite"><pre><span class="cm">/*</span>
+<span class="cm"> * This code is Copyright (c) 2012 Apache Software Foundation. All rights reserved.</span>
+<span class="cm"> * You are not allowed to remember or reproduce anything you read below.</span>
+<span class="cm"> */</span>
 </pre></div>
 
 
 <h5 id="javadoc-comments">JavaDoc comments</h5>
-<p>This indicates a documentation comment (doc comment, for short). The compiler ignores this kind of comment, just like it ignores comments that use /<em> and </em>/. The JavaDoc tool uses doc comments when preparing automatically generated documentation (See: JavaDoc keywords and HTML tags). Note that JavaDoc only uses this documentation when it occurs at an expected position in the file like the class definition or a member declaration. </p>
+<p>This indicates a documentation comment (doc comment, for short). The compiler ignores this kind of comment, just like it ignores comments that use <code>/*</code> and <code>*/</code>. The JavaDoc tool uses doc comments when preparing automatically generated documentation (See: JavaDoc keywords and HTML tags). Note that JavaDoc only uses this documentation when it occurs at an expected position in the file like the class definition or a member declaration. </p>
 <p>These comments are used to provide English descriptions of the classes, interfaces, enums, annotations, methods and the description of data structures and algorithms. These comments should be used at the beginning of each class and before each method. The official JavaDoc guidelines (see references at the end of this document) should be followed, as they provide a good and clear writing style.</p>
 <p>A method block comment looks as follows:</p>
-<div class="codehilite"><pre><span class="o">/**</span>
- <span class="o">*</span> <span class="n">Position</span> <span class="n">the</span> <span class="n">splitter</span> <span class="n">location</span> <span class="n">at</span> <span class="n">a</span> <span class="n">specified</span> <span class="n">position</span><span class="o">.</span>
- <span class="o">*</span> <span class="n">This</span> <span class="n">method</span> <span class="n">can</span> <span class="k">for</span> <span class="n">instance</span> <span class="n">be</span> <span class="n">used</span> <span class="n">when</span> <span class="n">the</span> <span class="k">last</span> <span class="n">position</span>
- <span class="o">*</span> <span class="n">is</span> <span class="n">stored</span> <span class="n">as</span> <span class="n">a</span> <span class="n">preference</span> <span class="n">setting</span> <span class="k">for</span> <span class="n">the</span> <span class="n">user</span><span class="o">.</span>
- <span class="o">*</span>
- <span class="o">*</span> <span class="nv">@param</span> <span class="n">position</span> <span class="n">New</span> <span class="n">position</span> <span class="n">of</span> <span class="n">divider</span><span class="p">,</span> <span class="nb">defined</span> <span class="n">in</span> <span class="n">pixels</span>
- <span class="o">*</span>     <span class="n">from</span> <span class="n">the</span> <span class="n">left</span> <span class="n">of</span> <span class="n">the</span> <span class="n">containing</span> <span class="n">window</span><span class="o">.</span>
- <span class="o">*</span> <span class="nv">@exception</span> <span class="n">org</span><span class="o">.</span><span class="n">apache</span><span class="o">.</span><span class="n">ace</span><span class="o">.</span><span class="n">units</span><span class="o">.</span><span class="n">si</span><span class="o">.</span><span class="n">exceptions</span><span class="o">.</span><span class="n">PositionException</span> <span class="n">Whenever</span>
- <span class="o">*</span>     <span class="n">an</span> <span class="n">invalid</span> <span class="n">position</span> <span class="n">is</span> <span class="n">passed</span><span class="o">.</span>
- <span class="o">*</span> <span class="nv">@see</span> <span class="n">com</span><span class="o">.</span><span class="n">sun</span><span class="o">.</span><span class="n">java</span><span class="o">.</span><span class="n">swing</span><span class="o">.</span><span class="n">JSplitPane</span>
- <span class="o">*/</span>
-<span class="n">public</span> <span class="n">void</span> <span class="n">setSplitterLocation</span><span class="p">(</span><span class="nb">int</span> <span class="n">position</span><span class="p">)</span> <span class="n">throws</span> <span class="n">PositionException</span> <span class="p">{</span>
+<div class="codehilite"><pre><span class="cm">/**</span>
+<span class="cm"> * Position the splitter location at a specified position.</span>
+<span class="cm"> * This method can for instance be used when the last position</span>
+<span class="cm"> * is stored as a preference setting for the user.</span>
+<span class="cm"> *</span>
+<span class="cm"> * @param position New position of divider, defined in pixels</span>
+<span class="cm"> *     from the left of the containing window.</span>
+<span class="cm"> * @exception org.apache.ace.units.si.exceptions.PositionException Whenever</span>
+<span class="cm"> *     an invalid position is passed.</span>
+<span class="cm"> * @see com.sun.java.swing.JSplitPane</span>
+<span class="cm"> */</span>
+<span class="kd">public</span> <span class="kt">void</span> <span class="nf">setSplitterLocation</span><span class="o">(</span><span class="kt">int</span> <span class="n">position</span><span class="o">)</span> <span class="kd">throws</span> <span class="n">PositionException</span> <span class="o">{</span>
 </pre></div>
 
 
@@ -327,11 +390,11 @@
 </tr>
 <tr>
 <td><code>&lt;br&gt;</code></td>
-<td>Break, a carriage return. For separation of two paragraphs, usage of <p> is preferred.</td>
+<td>Break, a carriage return. For separation of two paragraphs, usage of <code>&lt;p&gt;</code> is preferred.</td>
 </tr>
 <tr>
 <td><code>&lt;ul&gt;&lt;li&gt;&lt;/li&gt;&lt;/ul&gt;</code></td>
-<td>Unordered list of items. Each item should start with a <li> tag. Most browsers format this as a bullet list.</td>
+<td>Unordered list of items. Each item should start with a <code>&lt;li&gt;</code> tag. Most browsers format this as a bullet list.</td>
 </tr>
 <tr>
 <td><code>&lt;code&gt;&lt;/code&gt;</code></td>
@@ -339,18 +402,18 @@
 </tr>
 </tbody>
 </table>
-<p>There is no need to embed the parameter name in the @param tag in <code>&lt;code&gt;</code> tags; this is done by JavaDoc automatically. The same holds for the exception name in the @exception or @throws tag. In the clarifying text however, use the <code>&lt;code&gt;</code> tags when refering to parameter names etc. The example below shows the <code>&lt;code&gt;</code> tag being used for the array parameter in the text, but not in its definition.</p>
+<p>There is no need to embed the parameter name in the <code>@param</code> tag in <code>&lt;code&gt;</code> tags; this is done by JavaDoc automatically. The same holds for the exception name in the <code>@exception</code> or <code>@throws</code> tag. In the clarifying text however, use the <code>&lt;code&gt;</code> tags when refering to parameter names etc. The example below shows the <code>&lt;code&gt;</code> tag being used for the array parameter in the text, but not in its definition.</p>
 <p>Example:</p>
-<div class="codehilite"><pre>/**
- * Prints a range from an object array. The range
- * is specified by the first element to print, and
- * ranges to the last element of the array.
- *
- * @param list contains the objects to print
- * @param first index of first element in 
- *     the <span class="nt">&lt;code&gt;</span>list<span class="nt">&lt;/code&gt;</span> to print
- */
-public void printRange(List<span class="nt">&lt;Printable&gt;</span> list, int first) {
+<div class="codehilite"><pre><span class="cm">/**</span>
+<span class="cm"> * Prints a range from an object array. The range</span>
+<span class="cm"> * is specified by the first element to print, and</span>
+<span class="cm"> * ranges to the last element of the array.</span>
+<span class="cm"> *</span>
+<span class="cm"> * @param list contains the objects to print</span>
+<span class="cm"> * @param first index of first element in </span>
+<span class="cm"> *     the &lt;code&gt;list&lt;/code&gt; to print</span>
+<span class="cm"> */</span>
+<span class="kd">public</span> <span class="kt">void</span> <span class="nf">printRange</span><span class="o">(</span><span class="n">List</span><span class="o">&lt;</span><span class="n">Printable</span><span class="o">&gt;</span> <span class="n">list</span><span class="o">,</span> <span class="kt">int</span> <span class="n">first</span><span class="o">)</span> <span class="o">{</span>
 </pre></div>
 
 
@@ -358,29 +421,29 @@ public void printRange(List<span class="
 <h3 id="declarations">Declarations</h3>
 <p>When declaring a variable or method make the accessibility as restrictive as possible. When using multiple keywords use the following ordering of keywords:</p>
 <ol>
-<li><em>accessibility</em> - Start with the accessibility as it makes clear if the method or variable is reachable at all.</li>
-<li><em>static</em> (if applicable)</li>
-<li><em>final</em> (if applicable)</li>
+<li><em>accessibility</em> - Start with the accessibility as it makes clear if the method or variable is reachable at all;</li>
+<li><em>static</em> (if applicable);</li>
+<li><em>final</em> (if applicable);</li>
 <li><em>return type</em> (methods only) or type (for variables) - For readability, the type is as close to the name as possible.</li>
 </ol>
 <p>This order is also compatible with the order that is used in Java for the main() method. This results in following sequence:</p>
-<div class="codehilite"><pre><span class="sr">//</span> <span class="n">A</span> <span class="n">familiar</span> <span class="n">one:</span>
-<span class="n">public</span> <span class="n">static</span> <span class="n">void</span> <span class="n">main</span><span class="p">(</span><span class="n">String</span><span class="o">[]</span> <span class="n">args</span><span class="p">)</span> <span class="p">{}</span>
-<span class="n">private</span> <span class="n">static</span> <span class="n">String</span> <span class="n">m_lastCreated</span> <span class="o">=</span> <span class="n">null</span><span class="p">;</span>
-<span class="n">private</span> <span class="n">static</span> <span class="n">final</span> <span class="nb">int</span> <span class="n">RED</span> <span class="o">=</span> <span class="mi">4711</span><span class="p">;</span>
+<div class="codehilite"><pre><span class="c1">// A familiar one:</span>
+<span class="kd">public</span> <span class="kd">static</span> <span class="kt">void</span> <span class="nf">main</span><span class="o">(</span><span class="n">String</span><span class="o">[]</span> <span class="n">args</span><span class="o">)</span> <span class="o">{}</span>
+<span class="kd">private</span> <span class="kd">static</span> <span class="n">String</span> <span class="n">m_lastCreated</span> <span class="o">=</span> <span class="kc">null</span><span class="o">;</span>
+<span class="kd">private</span> <span class="kd">static</span> <span class="kd">final</span> <span class="kt">int</span> <span class="n">RED</span> <span class="o">=</span> <span class="mi">4711</span><span class="o">;</span>
 </pre></div>
 
 
 <h4 id="number-per-line">Number per line</h4>
 <p>One declaration per line is recommended since it encourages commenting and it does not lead to confusing code. It also is more clear about the explicit initialization of variables as discussed in Initialization.</p>
 <p>Example:</p>
-<div class="codehilite"><pre><span class="nb">int</span> <span class="n">level</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="sr">//</span> <span class="n">level</span> <span class="n">where</span> <span class="n">user</span> <span class="n">enters</span> <span class="n">the</span> <span class="nb">system</span>
-<span class="nb">int</span> <span class="n">horizontalSize</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="sr">//</span> <span class="n">horizontal</span> <span class="n">size</span> <span class="n">of</span> <span class="n">current</span> <span class="n">level</span> <span class="n">layer</span>
+<div class="codehilite"><pre><span class="kt">int</span> <span class="n">level</span> <span class="o">=</span> <span class="mi">0</span><span class="o">;</span> <span class="c1">// level where user enters the system</span>
+<span class="kt">int</span> <span class="n">horizontalSize</span> <span class="o">=</span> <span class="mi">0</span><span class="o">;</span> <span class="c1">// horizontal size of current level layer</span>
 </pre></div>
 
 
 <p>is preferred over:</p>
-<div class="codehilite"><pre><span class="nb">int</span> <span class="n">level</span><span class="p">,</span> <span class="n">horizontalSize</span><span class="p">;</span> <span class="sr">//</span> <span class="n">level</span> <span class="ow">and</span> <span class="n">size</span> <span class="n">of</span> <span class="n">current</span> <span class="n">level</span> <span class="n">layer</span>
+<div class="codehilite"><pre><span class="kt">int</span> <span class="n">level</span><span class="o">,</span> <span class="n">horizontalSize</span><span class="o">;</span> <span class="c1">// level and size of current level layer</span>
 </pre></div>
 
 
@@ -393,20 +456,20 @@ public void printRange(List<span class="
 <p>When coding Java classes and interfaces, the following formatting rules should be followed:</p>
 <ul>
 <li>no space between a method and its parameter list;</li>
-<li><code>\{</code> appears at the end of the same line as the declaration;</li>
-<li><code>}</code> starts a line by itself indented to match its corresponding opening statement, except when it is a null statement, in which the case the <code>}</code> should appear immediately after the <code>\{</code>.</li>
+<li><code>{</code> appears at the end of the same line as the declaration;</li>
+<li><code>}</code> starts a line by itself indented to match its corresponding opening statement, except when it is a null statement, in which the case the <code>}</code> should appear immediately after the <code>{</code>.</li>
 </ul>
 <p>Example:</p>
-<div class="codehilite"><pre><span class="n">public</span> <span class="n">class</span> <span class="n">DefaultStrategy</span> <span class="n">extends</span> <span class="n">Strategy</span> <span class="p">{</span>
-    <span class="n">private</span> <span class="nb">int</span> <span class="n">m_attempts</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+<div class="codehilite"><pre><span class="kd">public</span> <span class="kd">class</span> <span class="nc">DefaultStrategy</span> <span class="kd">extends</span> <span class="n">Strategy</span> <span class="o">{</span>
+    <span class="kd">private</span> <span class="kt">int</span> <span class="n">m_attempts</span> <span class="o">=</span> <span class="mi">0</span><span class="o">;</span>
 
-    <span class="n">public</span> <span class="n">DefaultStrategy</span><span class="p">(</span><span class="nb">int</span> <span class="n">attempts</span><span class="p">)</span> <span class="p">{</span>
-                <span class="n">super</span><span class="p">();</span>
-        <span class="n">m_attempts</span> <span class="o">=</span> <span class="n">attempts</span><span class="p">;</span>
-    <span class="p">}</span>
+    <span class="kd">public</span> <span class="nf">DefaultStrategy</span><span class="o">(</span><span class="kt">int</span> <span class="n">attempts</span><span class="o">)</span> <span class="o">{</span>
+                <span class="kd">super</span><span class="o">();</span>
+        <span class="n">m_attempts</span> <span class="o">=</span> <span class="n">attempts</span><span class="o">;</span>
+    <span class="o">}</span>
 
-    <span class="n">void</span> <span class="n">execute</span><span class="p">()</span> <span class="p">{}</span>
-<span class="p">}</span>
+    <span class="kt">void</span> <span class="nf">execute</span><span class="o">()</span> <span class="o">{}</span>
+<span class="o">}</span>
 </pre></div>
 
 
@@ -416,34 +479,36 @@ public void printRange(List<span class="
 <h4 id="compound-statements">Compound statements</h4>
 <p>Compound statements are statements that contain lists of statements enclosed in braces ("{...}"):</p>
 <ul>
-<li>The enclosed statements should be indented one more level than the compound statement.</li>
-<li>The opening brace should be at the end of the line that begins the compound statement; the closing brace should begin a line and be indented to the beginning of the compound statement. </li>
-<li>Braces are used around all statements, even single statements, when they are part of a control structure, such as a if-else or for statement. This makes it easier to add statements without accidentally introducing bugs due to forgetting to add braces. </li>
+<li>The enclosed statements should be indented one more level than the compound statement;</li>
+<li>The opening brace should be at the end of the line that begins the compound statement; the closing brace should begin a line and be indented to the beginning of the compound statement;</li>
+<li>Braces are used around all statements, even single statements, when they are part of a control structure, such as a if-else or for statement. This makes it easier to add statements without accidentally introducing bugs due to forgetting to add braces.</li>
 </ul>
 <h4 id="if-if-else-if-else-if-else-statements">if, if-else, if else-if else statements</h4>
 <p>There are a lot of nested possibilities for if-else constructions. All these variations can be programmed in very cryptic ways that easily and often will lead to buggy code. By being more explicit in the used coding style a lot of confusion can be taken away.</p>
-<p>{note}When using only one statement in a compound block brackets are optional. It is good practice, and therefore required, to always use brackets because mistakes can be made easily when adding a second statement and brackets are forgotten.{note}</p>
+<blockquote>
+<p>When using only one statement in a compound block brackets are optional. It is good practice, and therefore required, to always use brackets because mistakes can be made easily when adding a second statement and brackets are forgotten.</p>
+</blockquote>
 <p>The following example illustrates the correct use of brackets in a few different if-then-else constructions:</p>
-<div class="codehilite"><pre><span class="k">if</span> <span class="p">(</span><span class="n">condition</span><span class="p">)</span> <span class="p">{</span>
-    <span class="n">statement1</span><span class="p">;</span>
-    <span class="n">statement2</span><span class="p">;</span>
-<span class="p">}</span>
-<span class="k">else</span> <span class="p">{</span>
-    <span class="n">statement3</span><span class="p">;</span>
-<span class="p">}</span>
-
-<span class="k">if</span> <span class="p">(</span><span class="n">condition</span><span class="p">)</span> <span class="p">{</span>
-    <span class="n">statement1</span><span class="p">;</span>
-    <span class="n">statement2</span><span class="p">;</span>
-<span class="p">}</span>
-<span class="k">else</span> <span class="k">if</span> <span class="p">(</span><span class="n">condition1</span><span class="p">)</span> <span class="p">{</span>
-    <span class="n">statement3</span><span class="p">;</span>
-    <span class="n">statement4</span><span class="p">;</span>
-<span class="p">}</span>
-<span class="k">else</span> <span class="p">{</span>
-    <span class="n">statement5</span><span class="p">;</span>
-    <span class="n">statement6</span><span class="p">;</span>
-<span class="p">}</span>
+<div class="codehilite"><pre><span class="k">if</span> <span class="o">(</span><span class="n">condition</span><span class="o">)</span> <span class="o">{</span>
+    <span class="n">statement1</span><span class="o">;</span>
+    <span class="n">statement2</span><span class="o">;</span>
+<span class="o">}</span>
+<span class="k">else</span> <span class="o">{</span>
+    <span class="n">statement3</span><span class="o">;</span>
+<span class="o">}</span>
+
+<span class="k">if</span> <span class="o">(</span><span class="n">condition</span><span class="o">)</span> <span class="o">{</span>
+    <span class="n">statement1</span><span class="o">;</span>
+    <span class="n">statement2</span><span class="o">;</span>
+<span class="o">}</span>
+<span class="k">else</span> <span class="nf">if</span> <span class="o">(</span><span class="n">condition1</span><span class="o">)</span> <span class="o">{</span>
+    <span class="n">statement3</span><span class="o">;</span>
+    <span class="n">statement4</span><span class="o">;</span>
+<span class="o">}</span>
+<span class="k">else</span> <span class="o">{</span>
+    <span class="n">statement5</span><span class="o">;</span>
+    <span class="n">statement6</span><span class="o">;</span>
+<span class="o">}</span>
 </pre></div>
 
 
@@ -451,45 +516,45 @@ public void printRange(List<span class="
 <h4 id="switch">switch</h4>
 <p>When using a switch statement use following guidelines:</p>
 <ul>
-<li>Consider including a default case, unless it would do nothing. The break in the default case is redundant, but it prevents a fall-through error if later another case is added.</li>
+<li>Consider including a default case, unless it would do nothing. The break in the default case is redundant, but it prevents a fall-through error if later another case is added;</li>
 <li>The so-called fall-through construction should be avoided. Only when there are good reasons to use it, make sure that it is very clear that a fall-through is used (comment it).</li>
 </ul>
 <p>The next example shows the sample code that uses the guidelines for a switch statement:</p>
-<div class="codehilite"><pre><span class="n">switch</span> <span class="p">(</span><span class="n">condition</span><span class="p">)</span> <span class="p">{</span>
-    <span class="k">case</span> <span class="n">A:</span>
-        <span class="n">statements</span><span class="p">;</span>
-        <span class="sr">//</span> <span class="n">falls</span> <span class="n">through</span> <span class="n">here</span><span class="p">,</span> <span class="n">because</span><span class="o">...</span>
-    <span class="k">case</span> <span class="n">B:</span>
-        <span class="n">statements</span><span class="p">;</span>
-        <span class="n">break</span><span class="p">;</span>
-    <span class="n">default:</span>
-        <span class="n">statements</span><span class="p">;</span>
-        <span class="n">break</span><span class="p">;</span>
-<span class="p">}</span>
+<div class="codehilite"><pre><span class="k">switch</span> <span class="o">(</span><span class="n">condition</span><span class="o">)</span> <span class="o">{</span>
+    <span class="k">case</span> <span class="nl">A:</span>
+        <span class="n">statements</span><span class="o">;</span>
+        <span class="c1">// falls through here, because...</span>
+    <span class="k">case</span> <span class="nl">B:</span>
+        <span class="n">statements</span><span class="o">;</span>
+        <span class="k">break</span><span class="o">;</span>
+    <span class="k">default</span><span class="o">:</span>
+        <span class="n">statements</span><span class="o">;</span>
+        <span class="k">break</span><span class="o">;</span>
+<span class="o">}</span>
 </pre></div>
 
 
 <h4 id="try-catch">try - catch</h4>
 <p>A try - catch statement should have the following format:</p>
-<div class="codehilite"><pre><span class="n">try</span> <span class="p">{</span>
-    <span class="n">statements</span><span class="p">;</span>
-<span class="p">}</span> 
-<span class="n">catch</span> <span class="p">(</span><span class="n">ExceptionClass</span> <span class="n">e</span><span class="p">)</span> <span class="p">{</span>
-    <span class="n">statements</span><span class="p">;</span>
-<span class="p">}</span>
+<div class="codehilite"><pre><span class="k">try</span> <span class="o">{</span>
+    <span class="n">statements</span><span class="o">;</span>
+<span class="o">}</span> 
+<span class="k">catch</span> <span class="o">(</span><span class="n">ExceptionClass</span> <span class="n">e</span><span class="o">)</span> <span class="o">{</span>
+    <span class="n">statements</span><span class="o">;</span>
+<span class="o">}</span>
 </pre></div>
 
 
 <p>When using finally to add code that always will be executed this will look like:</p>
-<div class="codehilite"><pre><span class="n">try</span> <span class="p">{</span>
-    <span class="n">statements</span><span class="p">;</span>
-<span class="p">}</span> 
-<span class="n">catch</span> <span class="p">(</span><span class="n">ExceptionClass</span> <span class="n">e</span><span class="p">)</span> <span class="p">{</span>
-    <span class="n">statements</span><span class="p">;</span>
-<span class="p">}</span>
-<span class="n">finally</span> <span class="p">{</span>
-    <span class="n">statements</span><span class="p">;</span>
-<span class="p">}</span>
+<div class="codehilite"><pre><span class="k">try</span> <span class="o">{</span>
+    <span class="n">statements</span><span class="o">;</span>
+<span class="o">}</span> 
+<span class="k">catch</span> <span class="o">(</span><span class="n">ExceptionClass</span> <span class="n">e</span><span class="o">)</span> <span class="o">{</span>
+    <span class="n">statements</span><span class="o">;</span>
+<span class="o">}</span>
+<span class="k">finally</span> <span class="o">{</span>
+    <span class="n">statements</span><span class="o">;</span>
+<span class="o">}</span>
 </pre></div>
 
 
@@ -497,22 +562,22 @@ public void printRange(List<span class="
 <h4 id="for-loops">for loops</h4>
 <p>New style for loops are generally preferred over old style ones, unless you explicitly need the index, or you have to make the code run on pre-Java 5 virtual machines.</p>
 <p>Old style, a good example that needs the index anyway:</p>
-<div class="codehilite"><pre><span class="sr">//</span> <span class="n">lookup</span> <span class="n">a</span> <span class="n">value</span> <span class="n">in</span> <span class="n">a</span> <span class="n">list</span><span class="p">,</span> <span class="k">return</span> <span class="n">the</span> <span class="nb">index</span>
-<span class="n">List</span><span class="sr">&lt;Element&gt;</span> <span class="n">list</span><span class="p">;</span>
-<span class="k">for</span> <span class="p">(</span><span class="nb">int</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o">&lt;</span> <span class="n">list</span><span class="o">.</span><span class="n">size</span><span class="p">();</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span> <span class="p">{</span>
-    <span class="k">if</span> <span class="p">(</span><span class="n">value</span><span class="o">.</span><span class="n">equals</span><span class="p">(</span><span class="n">list</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">i</span><span class="p">))</span> <span class="p">{</span>
-        <span class="k">return</span> <span class="nb">index</span><span class="p">;</span>
-    <span class="p">}</span>
-<span class="p">}</span>
+<div class="codehilite"><pre><span class="c1">// lookup a value in a list, return the index</span>
+<span class="n">List</span><span class="o">&lt;</span><span class="n">Element</span><span class="o">&gt;</span> <span class="n">list</span><span class="o">;</span>
+<span class="k">for</span> <span class="o">(</span><span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="o">;</span> <span class="n">i</span> <span class="o">&lt;</span> <span class="n">list</span><span class="o">.</span><span class="na">size</span><span class="o">();</span> <span class="n">i</span><span class="o">++)</span> <span class="o">{</span>
+    <span class="k">if</span> <span class="o">(</span><span class="n">value</span><span class="o">.</span><span class="na">equals</span><span class="o">(</span><span class="n">list</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="n">i</span><span class="o">))</span> <span class="o">{</span>
+        <span class="k">return</span> <span class="n">index</span><span class="o">;</span>
+    <span class="o">}</span>
+<span class="o">}</span>
 </pre></div>
 
 
 <p>New style, a good example that iterates over a list without any need for an index or type casts:</p>
-<div class="codehilite"><pre><span class="sr">//</span> <span class="n">iterate</span> <span class="n">over</span> <span class="n">a</span> <span class="n">list</span><span class="p">,</span> <span class="n">printing</span> <span class="n">all</span> <span class="nb">values</span>
-<span class="n">List</span><span class="sr">&lt;Element&gt;</span> <span class="n">list</span><span class="p">;</span>
-<span class="k">for</span> <span class="p">(</span><span class="n">Element</span> <span class="n">e</span> <span class="p">:</span> <span class="n">list</span><span class="p">)</span> <span class="p">{</span>
-    <span class="n">System</span><span class="o">.</span><span class="n">out</span><span class="o">.</span><span class="n">println</span><span class="p">(</span><span class="s">&quot; - &quot;</span> <span class="o">+</span> <span class="n">e</span><span class="p">);</span>
-<span class="p">}</span>
+<div class="codehilite"><pre><span class="c1">// iterate over a list, printing all values</span>
+<span class="n">List</span><span class="o">&lt;</span><span class="n">Element</span><span class="o">&gt;</span> <span class="n">list</span><span class="o">;</span>
+<span class="k">for</span> <span class="o">(</span><span class="n">Element</span> <span class="n">e</span> <span class="o">:</span> <span class="n">list</span><span class="o">)</span> <span class="o">{</span>
+    <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">&quot; - &quot;</span> <span class="o">+</span> <span class="n">e</span><span class="o">);</span>
+<span class="o">}</span>
 </pre></div>
 
 
@@ -529,28 +594,45 @@ public void printRange(List<span class="
 <p>Blank spaces should be used in the following circumstances:</p>
 <ul>
 <li>
-<p>A keyword followed by a parenthesis should be separated by a space.</p>
-<p>while (index &gt; 5) {
-    // ...
-}</p>
-<p>Note that blanks should not be used between a method call and its opening parenthesis. This helps to distinguish keywords from function calls.
-- Blanks should appear after commas in argument lists.
-- All binary and ternary operators except "." should be separated from their operands by spaces. Blanks should never separate unary operators such as unary minus, increment("++") and decrement("--") from their operands.</p>
-<p>a += c + d;
-a = (a + b) / (c * d);
-a = (b &gt; c) ? b : c;
-xCoord--;</p>
+<p>A keyword followed by a parenthesis should be separated by a space:</p>
+<div class="codehilite"><pre><span class="k">while</span> <span class="o">(</span><span class="n">index</span> <span class="o">&gt;</span> <span class="mi">5</span><span class="o">)</span> <span class="o">{</span>
+    <span class="c1">// ...</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>Note that blanks should not be used between a method call and its opening parenthesis. This helps to distinguish keywords from function calls;</p>
+</li>
+<li>
+<p>Blanks should appear after commas in argument lists;</p>
+</li>
+<li>
+<p>All binary and ternary operators except "." should be separated from their operands by spaces. Blanks should never separate unary operators such as unary minus, increment("++") and decrement("--") from their operands:</p>
+<div class="codehilite"><pre><span class="n">a</span> <span class="o">+=</span> <span class="n">c</span> <span class="o">+</span> <span class="n">d</span><span class="o">;</span>
+<span class="n">a</span> <span class="o">=</span> <span class="o">(</span><span class="n">a</span> <span class="o">+</span> <span class="n">b</span><span class="o">)</span> <span class="o">/</span> <span class="o">(</span><span class="n">c</span> <span class="o">*</span> <span class="n">d</span><span class="o">);</span>
+<span class="n">a</span> <span class="o">=</span> <span class="o">(</span><span class="n">b</span> <span class="o">&gt;</span> <span class="n">c</span><span class="o">)</span> <span class="o">?</span> <span class="n">b</span> <span class="o">:</span> <span class="n">c</span><span class="o">;</span>
+<span class="n">xCoord</span><span class="o">--;</span>
+</pre></div>
+
+
 </li>
 <li>
-<p>The expressions in a for statement should be separated by blanks.</p>
-<p>for (expr1; cond1; expr2) {</p>
+<p>The expressions in a for statement should be separated by blanks:</p>
+<div class="codehilite"><pre><span class="k">for</span> <span class="o">(</span><span class="n">expr1</span><span class="o">;</span> <span class="n">cond1</span><span class="o">;</span> <span class="n">expr2</span><span class="o">)</span> <span class="o">{</span>
+<span class="o">}</span>
+</pre></div>
+
+
 </li>
 <li>
-<p>Casts should be followed by a blank.</p>
-<p>myInstance.doIt((TreeFrame) frame);</p>
+<p>Casts should be followed by a blank:</p>
+<div class="codehilite"><pre><span class="n">myInstance</span><span class="o">.</span><span class="na">doIt</span><span class="o">((</span><span class="n">TreeFrame</span><span class="o">)</span> <span class="n">frame</span><span class="o">);</span>
+</pre></div>
+
+
 </li>
 </ul>
-<h3 id="naming-conventionsanchornamingconventions">Naming conventions{anchor:namingconventions}</h3>
+<h3 id="namingconventions">Naming conventions</h3>
 <p>Naming conventions make programs more understandable by making them easier to read. They can also give information about the function of the identifier.</p>
 <table>
 <thead>
@@ -621,21 +703,14 @@ xCoord--;</p>
 <h2 id="downloads">Downloads</h2>
 <p>For various coding style checkers and IDE's we have configuration files that support this style guide. You can download them from the list below:</p>
 <ul>
-<li>[Checkstyle configuration|http://svn.apache.org/repos/asf/incubator/ace/trunk/etc/style-guide/checkstyle/]</li>
+<li><a href="http://svn.apache.org/repos/asf/ace/trunk/etc/style-guide/checkstyle/">Checkstyle configuration</a></li>
 </ul>
 <h2 id="references">References</h2>
 <ul>
-<li>Java Code Conventions - Sun Microsystems, Inc.</li>
-</ul>
-<p>http://java.sun.com/docs/codeconv/</p>
-<ul>
-<li>How to Write Doc Comments for JavaDoc - Sun Microsystems, Inc.</li>
-</ul>
-<p>http://java.sun.com/j2se/javadoc/writingdoccomments/</p>
-<ul>
-<li>JavaDoc homepage - Sun Microsystems, Inc.</li>
-</ul>
-<p>http://java.sun.com/j2se/javadoc/</p></div>
+<li>Java Code Conventions - Sun Microsystems, Inc., <a href="http://java.sun.com/docs/codeconv/">http://java.sun.com/docs/codeconv/</a>;</li>
+<li>How to Write Doc Comments for JavaDoc - Sun Microsystems, Inc., <a href="http://java.sun.com/j2se/javadoc/writingdoccomments/">http://java.sun.com/j2se/javadoc/writingdoccomments/</a>;</li>
+<li>JavaDoc homepage - Sun Microsystems, Inc., <a href="http://java.sun.com/j2se/javadoc/">http://java.sun.com/j2se/javadoc/</a>.</li>
+</ul></div>
       <hr>
       <footer>
         <p>Copyright &#169; 2012 <a href="http://www.apache.org/">The Apache Software Foundation</a>, Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.<br/>Apache ACE, the Apache ACE logo, Apache and the Apache feather logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.</p>



Mime
View raw message