ace-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From j...@apache.org
Subject svn commit: r1327884 - /ace/site/trunk/content/dev-doc/coding-standards.mdtext
Date Thu, 19 Apr 2012 09:17:23 GMT
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/>.



Mime
View raw message