THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
...
Wiki Markup Do not use automatically expanded log or revision number provided by your source code management system unless it provides a facility to avoid "false conflicts" when doing merges due simply to revision number changes (which happens, for example, with cvs when branches are used). \[mandatory\]
Wiki Markup Every class that is to be released must be a member of a package \[mandatory\]. Rationale: classes that are not explicitly put in a package are placed in the unnamed package by the compiler. Therefore as the classes from many developers will be being placed in the same package the likelihood of a name clash is greatly increased.Wiki Markup All class imports from the same package should be grouped together. A single blank line should separate imports from different packages \[recommended\].
Wiki Markup Use javadoc tags and use HTML mark-up to enhance the readability of the output files \[mandatory\].
...
Wiki Markup Class names should start with a capital letter with every subsequent word capitalised, for example: DataProcessor \[mandatory\].
Wiki Markup All classes should be preceded by a javadoc comment describing the purpose of the class \[recommended\].Wiki Markup Class-level javadoc comments should specify the thread-safety of the class \[recommended\].Wiki Markup The name of exception classes should end in the word exception, for example: UnknownMungeException \[mandatory\].
Wiki Markup Class names should in general not be overloaded. For example, defining a class "com.foo.bar.String" should be avoided as there is already a class "java.lang.String" \[recommended\]. Rationale: adhering to this rule reduces the likelihood of confusion and means that the use of fully qualified class names should not be required.Wiki Markup The definition of the primary class (i.e. the class with the same name as the java file) should start in column 0 of the source file. Inner class definitions should be indented 4 spaces more than their enclosing class \[mandatory\].
Wiki Markup Declare a class as final only if specialisation will never be required and improved performance is essential. With modern JVMs there in fact may be no performance advantage. Warning: use of final limits code reuse \[mandatory\].
Wiki Markup For all but simplest classes the following methods should have useful definitions \[recommended\]:
Code Block public boolean equals(Object obj) public int hashCode() public String toString()
Wiki Markup The order of presentation of the sections in a class should be \[mandatory\]:
...
Wiki Markup Variable modifiers should be presented in the following order: static, final, transient, volatile \[mandatory\].
Wiki Markup The names of static final variables should be upper case with subsequent words prefixed with an underscore \[mandatory\]. For example:
Code Block public static final int NOT_FOUND = -1;
Wiki Markup When a subclass refers to a static final variable defined in a parent class, access should be qualified by specifying the defining class name \[mandatory\]. For example: use ParentClass.MAX rather than MAX.
Wiki Markup The names of variables (other that static final) should start with a lower case letter. Any words that are contained in the rest of the variable name should be capitalised \[mandatory\]. For example:
Code Block String name; String[] childrensNames;
Wiki Markup Class and instance variables must be prefixed with an underscore (_) \[mandatory\].
Wiki Markup Variables must not be named using the so-called Hungarian notation \[mandatory\]. For example:
Code Block int nCount = 4; // not allowed
Wiki Markup Only one variable may be defined per line \[mandatory\].
Wiki Markup Variable declarations should be indented 4 spaces more than their enclosing class \[mandatory\].
Wiki Markup All variables should be preceded by a javadoc comment that specifies what the variable is for, where it is used and so forth. The comment should be of the following form and be indented to the same level as the variable it refers to \[mandatoryrecommended\]
Wiki Markup Never declare instance variables as public unless the class is effectively a "struct" \[mandatory\].
Wiki Markup Never give a variable the same name as a variable in a superclass \[mandatory\].
Wiki Markup Ensure that all non-private class variables have sensible values even if no instances have been created (use static initialisers if necessary, i.e. "static \{ ... \}") \[mandatory\]. Rationale: prevents other objects accessing fields with undefined/unexpected values.Methods
This section gives guidelines for class and instance method definitions in Java. In this section if a rule uses the term method rather than instance method or class method, then the rule applies to both types of method.Wiki Markup Constructors and finalize methods should follow immediately after the variable declarations \[mandatory\].
Wiki Markup Do not call non-final methods from constructors. This can lead to unexpected results when the class is subclassed. If you must call non-final methods from constructors, document this in the constructor's javadoc \[mandatory\]. Note that private implies final.
Wiki Markup Methods that are associated with the same area of functionality should be physically close to one another \[recommended\].
Wiki Markup After grouping by functionality, methods should be presented in the following order \[recommended\]:
...
Wiki Markup Method modifiers should be presented in the following order: abstract, static, final., synchronized \[mandatory\]
Wiki Markup When a synchronized method is overloaded, it should be explicitly synchronized in the subclass \[recommended\].
Wiki Markup Method names should start with a lower case letter with all subsequent words being capitalised \[mandatory\]. For example:
Code Block protected int resize(int newSize) protected void addContentsTo(Container destinationContainer)
Wiki Markup Methods which get and set values should be named as follows \[mandatory\]:
Exceptions should be used to report any failure to get or set a value. The "@param" description should detail any assumptions made by the implementation, for example: "Specifying a null value will cause an error to be reported".Code Block Type getVariableName() void setVariableName(Type newValue)
Wiki Markup Method definitions should be indented 4 spaces more than their enclosing class \[mandatory\].
Wiki Markup All non-private methods should be preceded by a javadoc comment specifying what the method is for, detailing all arguments, returns and possible exceptions. This comment should be of the following form and be indented to the same level as the method it refers to \[mandatory\]:
Wiki Markup The braces associated with a method should be on a line on their own and be indented to the same level as the method \[mandatory\]. For example:
Code Block public void munge() { int i; // method definition omitted... }Wiki Markup The body of a method should be indented 4 columns further that the opening and closing braces associated with it \[mandatory\]. See the above rule for an example.
Wiki Markup When declaring and calling methods there should be no white space before or after the parenthesis \[mandatory\].
Wiki Markup In argument lists there should be no white space before a comma, and only a single space (or newline) after it \[mandatory\]. For example:
Code Block public void munge(int depth, String name) { if (depth > 0) { munge(depth - 1, name); } // do something }Wiki Markup Wherever reasonable define a default constructor (i.e. one that takes no arguments) so that Class.newInstance() may be used \[recommended\]. If an instance which was created by default construction could be used until further initialisation has been performed, then all unserviceable requests should cause a runtime exception to be thrown.
Wiki Markup The method public static void main() should not be used for test purposes. Instead a test/demo program should be supplied separately. \[mandatory\].
Wiki Markup Public access methods (i.e. methods that get and set attributes) should only be supplied when required \[mandatory\].
Wiki Markup If an instance method has no natural return value, declare it as void rather than using the "return this;" convention \[mandatory\].
Wiki Markup Ensure that non-private static methods behave sensibly if no instances of the defining class have been created \[mandatory\].
Expressions
This section defines the rules to be used for Java expressions:Wiki Markup Unary operators should not be separated from their operand by white space \[mandatory\].
Wiki Markup Embedded \+\+ or -- operators should only be used when it improves code clarity \[recommended\]. This is rare.
Wiki Markup Extra parenthesis should be used in expressions to improve their clarity \[recommended\].
Wiki Markup The logical expression operand of the "?:" (ternary) operator must be enclosed in parenthesis. If the other operands are also expressions then they should also be enclosed in parenthesis \[mandatory\]. For example:
Code Block biggest = (a > b) ? a : b; complex = (a + b > 100) ? (100 * c) : (10 * d);
Wiki Markup Nested "?:" (ternary) operators can be confusing and should be avoided \[mandatory\].
Wiki Markup Use of the binary "," operator (the comma operator) should be avoided \[mandatory\]. Putting all the work of a for loop on a single line is not a sign of great wisdom and talent.
Wiki Markup If an expression is too long for a line (i.e. extends beyond column 119) then it should be split after the lowest precedence operator near the break \[mandatory\]. For example:
Furthermore if an expression requires to be split more than once, then the split should occur at the same logical level if possible.Code Block if ((state == NEED_TO_REPLY) || (state == REPLY_ACK_TIMEOUT)) { // (re)send the reply and enter state WAITING_FOR_REPLY_ACK }Wiki Markup All binary and ternary operators (exception for ".") should be separated from their operands by a space \[mandatory\].
Statements
Simple Statements
This section defines the general rules for simple Java statements:
Wiki Markup There must only be one statement per line \[mandatory\].
Wiki Markup In general local variables should be named in a similar manner to instance variables \[recommended\].
Wiki Markup More than one temporary variable may be declared on a single line provided no initialisers are used \[mandatory\]. For example:
Code Block int j, k = 10, l; // Incorrect! int j, l; // Correct int k = 10;
Wiki Markup A null body for a while, for, if, etc. should be documented so that it is clearly intentional \[mandatory\].
Wiki Markup Keywords that are followed by a parenthesised expression (such as while, if, etc) should be separated from the open bracket by a single space \[mandatory\]. For example:
Code Block if (a > b) { munge(); }Wiki Markup In method calls, there should be no spaces before or after the parentheses \[mandatory\]. For example:
Code Block munge (a, 10); // Incorrect! munge(a, 10); // Correct.
Compound Statements
This section defines the general rules associated with compound statements in Java:
Wiki Markup The body of a compound statement should be indented by 4 spaces more than the enclosing braces \[mandatory\]. See the following rule for an example.
Wiki Markup The braces associated with a compound statement should be on their own line and be indented to the same level as the surrounding code \[mandatory\]. For example:
Code Block if ((length >= LEN_BOX) && (width >= WID_BOX)) { int i; // Statements omitted... }Wiki Markup If the opening and closing braces associated with a compound statement are further than 20 lines apart then the closing brace should annotated as follows \[mandatory\]:
Code Block for (int j = 0; j < SIZE; j++) { lotsOfCode(); } // end forWiki Markup All statements associated with an if or if-else statement should be made compound by the use of braces \[mandatory\]. For example:
Code Block if (a > b) { statement(); } else { statement1(); statement2(); }Wiki Markup The case labels in a switch statement should be on their own line and indented by a further 4 spaces. The statements associated with the label should be indented by 4 columns more than the label and not be enclosed in a compound statement. \[mandatory\]. For example:
Code Block switch (tState) { case NOT_RUNNING: start(); break; case RUNNING: default: monitor(); break; }Wiki Markup In switch statements - the statements associated with all cases should terminate with a statement which explicitly determines the flow of control, for example break \[recommended\].
Wiki Markup In switch statements - fall through should be avoided wherever possible, however if it is unavoidable it must be commented with "// FALLTHROUGH" \[mandatory\].
Wiki Markup In switch statements - a default case must be present and should always be the last case \[mandatory\].
General
This section gives general rules to be followed when programming in Java:Wiki Markup When comparing objects for equivalence use the method equals() and not the == operator. The only exceptions to this are static final objects that are being used as constants and interned Strings \[mandatory\].
Wiki Markup In general labelled break and continue statements should be avoided \[recommended\]. This is due to the complex flow of control, especially when used with try/finally blocks.
Wiki Markup Unless some aspect of an algorithm relies on it, then loops count forward \[mandatory\]. For example:
Code Block for (int j = 0; j < size; j++) { // Do something interesting }Wiki Markup Use local variables in loops \[recommended\]. For example:
Code Block ArrayList clone = (ArrayList)listeners.clone(); final int size = clone.size(); for (int j = 0; j < size; j++) { System.out.println(clone.elementAt(j)); }Wiki Markup Anonymous inner classes should define no instance variables and be limited to three single line methods. Inner classes that declare instance variables or have more complex methods should be named \[mandatory\].
Wiki Markup Use final local variables where possible to help avoid errors in code \[recommended\]. For example:
Code Block public void foo() { final int x = dataSource.getCount(); // do things with x // ... }Exceptions
This section gives general guidance on the use of exceptions when programming in Java.Wiki Markup try/catchTo blocksindicate shouldthat befurther laidwork is intended on a section of code, add a comment prefixed by "TODO" explaining what needs to be done and why \[recommended\].
Wiki Markup If code is so incomplete that executing it would lead to incorrect or confusing results, throw UnsupportedOperationException with an explanatory message \[mandatory\].
Exceptions
This section gives general guidance on the use of exceptions when programming in Java.
Wiki Markup try/catch blocks should be laid out out like any other compound statement \[mandatory\]. For example:
Code Block try { String str = someStrings[specifiedIndex]; } catch (IndexOutOfBoundsException ex) { // The user specified an incorrect index, better take // some remedial action. }Wiki Markup 4. When an exception is caught but ignored then a comment should be supplied explaining the rationale (note that this rule includes InterruptedException, which should almost never be ignored) \[mandatory\]. For example:
Code Block try { propertySet.setProperty("thingy", new Integer(10)); } catch (UnknownPropertyException ignore) { // This exception will never occur as "thingy" definitely exists }Wiki Markup All exceptions that are likely to be thrown by a method should be documented, except if they are runtime exceptions (note: the compiler will not enforce catch blocks for runtimes even if they are mentioned in the throws clause) \[mandatory\]. For example:
Code Block /* Comment snippet: * @exception IllegalValueException Thrown if values is null or * any of the integers it contains is null. */ private Integer sum(Integer[] values) throws IllegalValueException