Author: jawi
Date: Thu Apr 19 09:17:22 2012
New Revision: 1327884
URL: http://svn.apache.org/viewvc?rev=1327884&view=rev
Log:
CMS commit to ace by jawi
Modified:
ace/site/trunk/content/dev-doc/coding-standards.mdtext
Modified: ace/site/trunk/content/dev-doc/coding-standards.mdtext
URL:
http://svn.apache.org/viewvc/ace/site/trunk/content/dev-doc/coding-standards.mdtext?rev=1327884&r1=1327883&r2=1327884&view=diff
==============================================================================
--- ace/site/trunk/content/dev-doc/coding-standards.mdtext (original)
+++ ace/site/trunk/content/dev-doc/coding-standards.mdtext Thu Apr 19 09:17:22
2012
@@ -2,6 +2,8 @@ Title: Coding Standards
This is a Java coding style guide for the Apache ACE project.
+[TOC]
+
Summary
-------
@@ -42,6 +44,7 @@ Beginning comments are used for licensin
The first non-comment line of most Java source files is a package statement.
After an empty line import statements can follow. For example:
+ :::java
package org.apache.ace.core.ui;
import java.awt.Frame;
@@ -49,14 +52,15 @@ The first non-comment line of most Java
A few notes must be made here:
-1. *Package rules.* 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].
-1. *Import statements* need to be explicit in order to overcome name clashes.
They must be grouped by name.
+1. *Package rules.* 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);
+1. *Import statements* need to be explicit in order to overcome name clashes.
They must be grouped by name;
1. *Import order.* 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.
##### Class, interface, enum and annotation declarations
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:
+ :::java
/**
* Configuration manager. Manages the configuration of an application. Has
features
* to import and export whole configurations and notifies components that
need to
@@ -79,6 +83,7 @@ inner classes | Are placed at the
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:
+ :::java
@Manageable(description = "Starts the system.")
public void start() {
// ...
@@ -86,13 +91,14 @@ Annotations for classes and methods shou
Annotations for parameters can be inlined like this:
+ :::java
public void setValue(@Validation("x > 0 && x < 10", "Should be between 0
and 10.") int x) {
// ...
}
### Indentation
-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.
+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.
#### Line length
@@ -120,8 +126,9 @@ The Java language supports three differe
##### Single line comments
-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.
+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.
+ :::java
int a; // acceleration of the car
// all names that should be searched
@@ -129,8 +136,9 @@ The compiler ignores everything from //
##### Block comments
-The compiler ignores everything from /* to */. Use this style for internal
comments and copyright headers.
+The compiler ignores everything from `/*` to `*/`. Use this style for internal
comments and copyright headers.
+ :::java
/*
* This code is Copyright (c) 2012 Apache Software Foundation. All rights
reserved.
* You are not allowed to remember or reproduce anything you read below.
@@ -138,12 +146,13 @@ The compiler ignores everything from /*
##### JavaDoc comments
-This indicates a documentation comment (doc comment, for short). The compiler
ignores this kind of comment, just like it ignores comments that use /* and */.
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.
+This indicates a documentation comment (doc comment, for short). The compiler
ignores this kind of comment, just like it ignores comments that use `/*` and
`*/`. 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.
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.
A method block comment looks as follows:
+ :::java
/**
* Position the splitter location at a specified position.
* This method can for instance be used when the last position
@@ -164,14 +173,15 @@ For class headers, method headers and me
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.
+`<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.
-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.
+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.
Example:
+ :::java
/**
* Prints a range from an object array. The range
* is specified by the first element to print, and
@@ -190,13 +200,14 @@ Java syntax and its layout
When declaring a variable or method make the accessibility as restrictive as
possible. When using multiple keywords use the following ordering of keywords:
-1. *accessibility* - Start with the accessibility as it makes clear if the
method or variable is reachable at all.
-1. *static* (if applicable)
-1. *final* (if applicable)
+1. *accessibility* - Start with the accessibility as it makes clear if the
method or variable is reachable at all;
+1. *static* (if applicable);
+1. *final* (if applicable);
1. *return type* (methods only) or type (for variables) - For readability, the
type is as close to the name as possible.
This order is also compatible with the order that is used in Java for the
main() method. This results in following sequence:
+ :::java
// A familiar one:
public static void main(String[] args) {}
private static String m_lastCreated = null;
@@ -208,11 +219,13 @@ One declaration per line is recommended
Example:
+ :::java
int level = 0; // level where user enters the system
int horizontalSize = 0; // horizontal size of current level layer
is preferred over:
+ :::java
int level, horizontalSize; // level and size of current level layer
#### Placement
@@ -230,11 +243,12 @@ Variables that are used and declared wit
When coding Java classes and interfaces, the following formatting rules should
be followed:
- no space between a method and its parameter list;
-- `\{` appears at the end of the same line as the declaration;
-- `}` starts a line by itself indented to match its corresponding opening
statement, except when it is a null statement, in which the case the `}` should
appear immediately after the `\{`.
+- `{` appears at the end of the same line as the declaration;
+- `}` starts a line by itself indented to match its corresponding opening
statement, except when it is a null statement, in which the case the `}` should
appear immediately after the `{`.
Example:
+ :::java
public class DefaultStrategy extends Strategy {
private int m_attempts = 0;
@@ -254,20 +268,21 @@ Each line should contain at most one sta
#### Compound statements
-Compound statements are statements that contain lists of statements enclosed
in braces ("\{...}"):
+Compound statements are statements that contain lists of statements enclosed
in braces ("{...}"):
-- The enclosed statements should be indented one more level than the compound
statement.
-- 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.
-- 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.
+- The enclosed statements should be indented one more level than the compound
statement;
+- 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;
+- 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.
#### if, if-else, if else-if else statements
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.
-{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}
+> 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.
The following example illustrates the correct use of brackets in a few
different if-then-else constructions:
+ :::java
if (condition) {
statement1;
statement2;
@@ -275,7 +290,7 @@ The following example illustrates the co
else {
statement3;
}
-
+
if (condition) {
statement1;
statement2;
@@ -295,11 +310,12 @@ Note that in the example the else if con
When using a switch statement use following guidelines:
-- 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.
+- 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;
- 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).
The next example shows the sample code that uses the guidelines for a switch
statement:
+ :::java
switch (condition) {
case A:
statements;
@@ -316,6 +332,7 @@ The next example shows the sample code t
A try - catch statement should have the following format:
+ :::java
try {
statements;
}
@@ -325,6 +342,7 @@ A try - catch statement should have the
When using finally to add code that always will be executed this will look
like:
+ :::java
try {
statements;
}
@@ -343,6 +361,7 @@ New style for loops are generally prefer
Old style, a good example that needs the index anyway:
+ :::java
// lookup a value in a list, return the index
List<Element> list;
for (int i = 0; i < list.size(); i++) {
@@ -353,6 +372,7 @@ Old style, a good example that needs the
New style, a good example that iterates over a list without any need for an
index or type casts:
+ :::java
// iterate over a list, printing all values
List<Element> list;
for (Element e : list) {
@@ -374,30 +394,37 @@ Blank lines improve readability by setti
Blank spaces should be used in the following circumstances:
-- A keyword followed by a parenthesis should be separated by a space.
-
- while (index > 5) {
- // ...
- }
+- A keyword followed by a parenthesis should be separated by a space:
- 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.
-
- a += c + d;
- a = (a + b) / (c * d);
- a = (b > c) ? b : c;
- xCoord--;
-
-- The expressions in a for statement should be separated by blanks.
-
- for (expr1; cond1; expr2) {
-
-- Casts should be followed by a blank.
+ :::java
+ while (index > 5) {
+ // ...
+ }
+
+ 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:
+
+ :::java
+ a += c + d;
+ a = (a + b) / (c * d);
+ a = (b > c) ? b : c;
+ xCoord--;
+
+- The expressions in a for statement should be separated by blanks:
+
+ :::java
+ for (expr1; cond1; expr2) {
+ }
- myInstance.doIt((TreeFrame) frame);
+- Casts should be followed by a blank:
+
+ :::java
+ myInstance.doIt((TreeFrame) frame);
-### Naming conventions{anchor:namingconventions}
+### Naming conventions {#namingconventions}
Naming conventions make programs more understandable by making them easier to
read. They can also give information about the function of the identifier.
@@ -420,19 +447,11 @@ Downloads
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:
-- [Checkstyle
configuration|http://svn.apache.org/repos/asf/incubator/ace/trunk/etc/style-guide/checkstyle/]
+- [Checkstyle
configuration](http://svn.apache.org/repos/asf/ace/trunk/etc/style-guide/checkstyle/)
References
----------
-- Java Code Conventions - Sun Microsystems, Inc.
-
- http://java.sun.com/docs/codeconv/
-
-- How to Write Doc Comments for JavaDoc - Sun Microsystems, Inc.
-
- http://java.sun.com/j2se/javadoc/writingdoccomments/
-
-- JavaDoc homepage - Sun Microsystems, Inc.
-
- http://java.sun.com/j2se/javadoc/
+- Java Code Conventions - Sun Microsystems, Inc.,
<http://java.sun.com/docs/codeconv/>;
+- How to Write Doc Comments for JavaDoc - Sun Microsystems, Inc.,
<http://java.sun.com/j2se/javadoc/writingdoccomments/>;
+- JavaDoc homepage - Sun Microsystems, Inc.,
<http://java.sun.com/j2se/javadoc/>.
