The following coding guidelines are a recommendation for the BASE 2 project. This document is based on the document Java Coding Conventions compiled by Per, but contains a lot more specific details.
ContentsGeneral | All names should be in English. Names should be descriptive and derived from the the domain the code is intended for. Try to avoid names longer than twenty characters. |
Packages | Package names must be in all lower case letters. |
Classes and Interfaces |
Names of classes and interfaces should be a concatenation
of one or more words. The initial letter of all words in the name, including
the first word, should be upper case letters. The rest of the characters
should be lower case. Example:
public class SoftwareType { ... } |
Constant member variables |
Constant member variables, usually defined static
final, should be named using all upper case characters. Words in the name
should be separated by underscore characters. Example:
public static final int VERSION_NUMBER; |
Private member variables |
Private member variables should be a concatenation of one or more descriptive
words. The initial letter of all words in the name, except
the first word, should be upper case letters. The rest of the characters
should be lower case.
Example:
private String loginComment; |
Methods |
Methods should be named using a descriptive statement,
usually made up by several words. Typically the first word is a verb, stating
the action and the others stating the target and attributes. Lower and upper
case letters should then be mixed, with all words in the name except the
first one starting with an upper case letter and the rest being in
lower case letters. Example:
public void setName(String name) { ... } |
Mutator (get/set) methods |
Avoid direct access to attributes (member variables)
from outside of a class. Instead make attributes private and use mutator
methods to access them. Prefix the mutator methods with get and set respectively
to fetch or change an attribute. If the getter returns a boolean value prefix
the mutator method with (typically) is, has or can. Examples:
public String getName() { ... } public boolean isActivated { ... } |
Exceptions |
The names of Exceptions must end with the word "Exception".
Example:
public class NoMoreNumbersException extends Exception { ... } |
Interface layout | Interfaces should only have public members, i.e. static attributes and method prototypes. |
White space | All code must be properly indented. In general each new block starts a new indentation level. Use tab when indenting. |
Code blocks |
The starting brace "{" of a code block should be placed
on a line by itself at the same indentation level as
the preceeding line of code. The first line in the new block
should be indented one tab-stop more. The ending brace "}" should
be placed at the same indentation level as the matching starting
brace. Example:
public String getName() { if (name == null) { return "unknown"; } else { return name; } } |
Javadoc |
Packages, classes, public methods and public attributes must be commented
in Javadoc style. It is recommended that private and protected methods
also has some comments, but maybe not as detailed as the public
ones.
|
Package comments |
Place package comments in a file named package.html in
the source code directory.
|
Class comments |
A class comment should start with a general description of the
class and what it does. The following tags must be present in this order:
|
Method comments |
A method comment should start with a general description of the
method and what it does. The following tags must be present in this order:
|
Attribute comments | If it is a static final attribute, describe what the attribute is for and where it is typically used. |
@base.internal | The @base.internal tag can be used to add comments that will only be visible in the internal documentation and hidden in the public documentation. |
Inline comments |
|
Todo comments |
If there are parts of the code that cannot be completed at
the time the majority of the code is written, place a comment
starting with TODO (in capital letters), followed with a description
of what needs to be done. Example:
public static Date copy(Date value) { return value == null ? null : new Date(value.getTime()); // TODO: check if there is a better way to copy } |
Subversion comment and GNU licence message |
Each file should start with a subversion comment and the GNU licence
and copyright message. Non-java files should also include this information,
in a format appropriate for the specific file.
/* $Id: generic.html 4477 2008-09-05 15:15:25Z jari $ Copyright (C) Authors contributing to this file. This file is part of BASE - BioArray Software Environment. Available at http://base.thep.lu.se/ BASE is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. BASE is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ |
Package and import statements |
The package statement is the first statement
to appear in the source file. All declared classes must belong to a named
package. It is not allowed for classes to belong to the "default" package,
i.e. to omit the package statement in the source file. Exception: Test code
may belong to the default package.
Import statements should follow directly after the package statement. Try to avoid preceeding class names in code with package names. Instead use import statements. Wildcards in import statements make it difficult to see dependencies, other than those to packages. Therefore import classes/interfaces explicitely. The only exception is when classes in subpackages to the current package are accessed. Such items are either imported explicitely or the whole subpackage may be imported with wildcard. However, avoid wildcard imports when subpackages are large - more than approximately 4 items.
Import statements should be in the following order:
Do not explicitely import packages or classes not used in your program code. |
Attributes and methods order |
Inside a class, attributes and methods should be organised in
the following order:
|
Classes and interfaces |
Class and interface statements should be organizied
in the following manner:
public class SomeClass extends SomeBase implements Clonable, SomeInterface { ... } public interface Testable extends Clonable { ... } |
Methods |
If a method throws checked exceptions, these should be declared
indented on a separate row directly after the method declaration. Example:
public int getNextValue(int previousValue) throws NoMoreValuesException { ... } |
Local variables | Local variables should be declared and initialized where they are used. They should be declared in the smallest possible scope. Avoid overloading variable names in inner blocks. |
Array declarations | The square brackets indicating an array of something should be immediately to the right of whatever class or datatype the array consists of (e.g. "String[] args") do not use C-style array declarations (String args[]). |
Conditional statements |
// IF-statements: if (...) { ... } else { ... } // FOR-statements: for (init; condition; update) { ... } // WHILE-statement: while (condition) { ... } // DO-WHILE-statement: do { ... } while (condition); // SWITCH-statement: switch (operand) { case: ... { ... } ... default: { ... } } // Exception blocks: try { ... } catch (SpecialException se) { ... } catch (Exception e) { ... } finally { ... } |