ace-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r804286 - /websites/staging/ace/trunk/content/dev-doc/coding-standards.html
Date Wed, 08 Feb 2012 23:11:46 GMT
Author: buildbot
Date: Wed Feb  8 23:11:46 2012
New Revision: 804286

Staging update by buildbot for ace


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 Wed Feb  8 23:11:46 2012
@@ -151,7 +151,388 @@
       <p><a href="/"><i class='icon-home'></i> Home</a>&nbsp;&raquo&nbsp;<a
       <h1>Coding Standards</h1>
       <div class="clear"></div>
-      <div id="content"></div>
+      <div id="content"><h2 id="introduction">Introduction</h2>
+<p>This is a Java coding style guide for the project.</p>
+<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>
+<p>This style guide is intended for those involved in the development of real software
systems written in Java. Different roles in a software project can exploit the style guide
in different ways. The programmer can use it as a reference on good Java style. It can be
used in code reviews as a common reference. Finally, lessons learned in real projects can
be captured by extending the style guide.</p>
+<h2 id="class-layout-and-comments">Class layout and comments</h2>
+<p>This chapter describes the layout for classes, interfaces, enums and annotations.
These all share a set of common properties, so they will be described together and for readability
all called 'classes' here.</p>
+<h3 id="files_and_filenames">Files and filenames</h3>
+<p>Files longer than 2000 lines are cumbersome and should be avoided.</p>
+<h4 id="file_names">File names</h4>
+<p>The file must be named after the class it represents. As for most cases each file
contains only one class, this is an easy naming convention. For nested or inner classes the
name of the main class must be the name of the file. As names in Java are case-sensitive,
the filename is case-sensitive also.</p>
+<h4 id="file_organization">File organization</h4>
+<p>Each Java source file contains a single class or interface. Of course, this excludes
inner classes as these must be defined without an (outer) class, and thus in the same file.</p>
+<p>Java source files have the following ordering:</p>
+<li>beginning comments;</li>
+<li>package and import statements;</li>
+<li>class and interface declarations.</li>
+<h4 id="beginning_comments">Beginning comments</h4>
+<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
+<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>
+<p>A few notes must be made here:</p>
+<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>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>
+<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>
+<p>The following table describes the parts of a class, interface, enum or annotation
declaration, in the order that they should appear.</p>
+<p>|| Part of declaration || Notes ||
+|documentation|According to comment block as shown above.|
+|class, interface, enum or annotation statement| |
+|(static) variables|These should be grouped by functionality rather than by scope.|
+|instance variables|These should be grouped by functionality rather than by scope.|
+|constructors|Start with the default constructor if any.|
+|methods|These methods should also be grouped by functionality rather than by scope or accessibility.
E.g. a private class method can be in between two public instance methods. The goal is to
make reading and understanding the code easier. When implementing an interface, group the
methods that are part of the interface.|
+|inner classes|Are placed at the bottom of the file.|</p>
+<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>
+<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>
+<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>
+<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
+<h4 id="wrapping_lines">Wrapping lines</h4>
+<p>When an expression will not fit on a single line, break it according to these general
+<li>break after a comma;</li>
+<li>break before an operator;</li>
+<li>prefer higher level breaks to lower level breaks;</li>
+<li>indent the new line with a tab;</li>
+<li>if the above rules lead to confusing code or to code that's squished up against
the right margin, please use common sense.</li>
+<h3 id="comment">Comment</h3>
+<h4 id="comment_styles">Comment styles</h4>
+<p>The Java language supports three different kinds of comments:</p>
+<li>single line comments;</li>
+<li>block comments;</li>
+<li>JavaDoc comments.</li>
+<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>
+<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
+<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
+ <span class="o">*/</span>
+<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>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
+ <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>
+<p>h5. HTML tags</p>
+<p>For class headers, method headers and member variables JavaDoc is used in order
to generate API documentation. Some HTML-tags that can be used in order to make the comment
blocks more readable:</p>
+<p>||Tag||Short description||
+|<p>|New paragraph.|
+|<br>|Break, a carriage return. For separation of two paragraphs, usage of <p>
is preferred.|
+|<ul><li></li></ul>|Unordered list of items. Each item should start
with a <li> tag. Most browsers format this as a bullet list.|
+|<code></code>|Code samples. Use this when refering to class names, method names,
parameter names, etc.|</p>
+<p>{note}There is no need to embed the parameter name in the @param tag in <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> tags when
refering to parameter names etc. The example below shows the <code> tag being used for
the array parameter in the text, but not in its definition.{note}</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) {
+<h2 id="java-syntax-and-its-layout">Java syntax and its layout</h2>
+<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>
+<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>
+<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>
+<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>
+<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>
+<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
+<h4 id="placement">Placement</h4>
+<p>In a method, declare local variables just before they are needed. This overcomes
the problem of a big list of parameters at the beginning of a method and the use of a variable
becomes more clearly in the context of the code, e.g. its initialization.</p>
+<h4 id="initialization">Initialization</h4>
+<p>The initialization of class variables is strictly not necessary because of the default
initialization that takes place for these kinds of members. For some types, e.g. Booleans,
this requires detailed knowledge of all the default values so it is more clear and explicit
to initialize each member. </p>
+<p>Variables that are used and declared within methods must always be initialized explicitly
(the compiler will generate an error when you forget this).</p>
+<h4 id="class_and_interface_declarations">Class and Interface Declarations</h4>
+<p>When coding Java classes and interfaces, the following formatting rules should be
+<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>
+<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
+    <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="n">void</span> <span class="n">execute</span><span
class="p">()</span> <span class="p">{}</span>
+<span class="p">}</span>
+<h3 id="statements">Statements</h3>
+<h4 id="simple_statements">Simple statements</h4>
+<p>Each line should contain at most one statement.</p>
+<h4 id="compound_statements">Compound statements</h4>
+<p>Compound statements are statements that contain lists of statements enclosed in
braces ("{...}"):</p>
+<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>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>
+<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>
+<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>
+<p>Note that in the example the else if construction is started at a new line so the
statement can not be overlooked.</p>
+<h4 id="switch">switch</h4>
+<p>When using a switch statement use following guidelines:</p>
+<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
+<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>
+<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
+    <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>
+<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
+    <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>
+<p>Note that the catch and the finally start at a new line in order to be compliant
to the guidelines for if-then-else statements.</p>
+<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
+    <span class="p">}</span>
+<span class="p">}</span>
+<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>
+<h3 id="white_space">White Space</h3>
+<h4 id="blank_lines">Blank lines</h4>
+<p>Blank lines improve readability by setting of sections of code that are logically
related. One blank line should always be used in the following circumstances:</p>
+<li>between class and interface definitions;</li>
+<li>between methods;</li>
+<li>before a block or single line comment;</li>
+<li>between logical sections inside a method to improve readability.</li>
+<h4 id="blank_spaces">Blank spaces</h4>
+<p>Blank spaces should be used in the following circumstances:</p>
+<p>A keyword followed by a parenthesis should be separated by a space.</p>
+<p>while (index &gt; 5) {
+    // ...
+<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>
+<p>Blanks should appear after commas in argument lists.</p>
+<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>
+<p>a += c + d;
+a = (a + b) / (c * d);
+a = (b &gt; c) ? b : c;
+<p>The expressions in a for statement should be separated by blanks.</p>
+<p>for (expr1; cond1; expr2) {</p>
+<p>Casts should be followed by a blank.</p>
+<p>myInstance.doIt((TreeFrame) frame);</p>
+<h3 id="naming_conventionsanchornamingconventions">Naming conventions{anchor:namingconventions}</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>
+<p>||Identifier Type||Rules for Naming||Examples||
+|(inner) classes, interfaces, enums and annotations|Names should be nouns, in mixed case
with the first letter of each word capitalised. Try to keep your names simple and descriptive.
Use whole words and avoid acronyms and abbreviations.|class Raster;\class TreeFrame;|
+|interfaces|Like class names, but if there is a name clash, the interface wins.|Repository|
+|services|Same as interfaces, so don't append "Service" as you usually do not know if an
interface is a service or not.|-|
+|implementation classes|If a class implements an interface, it should use the name of the
interface as part of its name, adding something specific for this implementation to it, or
Impl if that does not make sense.|class FileBasedRepository implements Repository; \class
VersionServlet implements HttpServlet; |
+|exceptions|Like class names; always ending in "Exception"|InputException|
+|methods|Methods should be verbs in mixed case with the first letter lowercase. Within each
method name capital letters separate words. Property methods or get-set methods are used as
+When a method is used to get a value start the method name with 'get'. When a method is used
to set a value start the method name with 'set'.|run(); \runFast(); \setBackground();|
+|variables (except for (constant) static final variables and member variables)|All variables
are in mixed case with a lowercase first letter. Words are separated by capital letters.|int
index;\float myWidth;|
+|member variables|The same capitalisation as for normal variables prefixed with 'm_'.|int
m_index;\float m_myWidth;|
+|constant (static final) variables, enum names|Names should be all uppercase with words separated
by underscores ("_").|public static final int BLACK = 99;|
+|packages|Lowercase only; avoid lengthy package names; always start with org.apache.ace.|org.apache.ace.demo.bundle|</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>
+<li>[Checkstyle configuration|]</li>
+<h2 id="references">References</h2>
+<li>Java Code Conventions - Sun Microsystems, Inc.
+<li>How to Write Doc Comments for JavaDoc - Sun Microsystems, Inc.
+<li>JavaDoc homepage - Sun Microsystems, Inc.
         <p>Copyright &#169; 2012 The Apache Software Foundation, Licensed under
the <a href="">Apache License, Version 2.0</a>.<br/>Apache
and the Apache feather logo are trademarks of The Apache Software Foundation.</p>

View raw message