BASE Development information General coding guidelines

General coding guidelines

NOTE! This document is outdated and has been replaced with newer documentation. See General coding style guidelines

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.

Contents
  1. Naming
  2. Layout and comments
  3. Statements

Last updated: $Date: 2011-06-27 14:06:13 +0200 (må, 27 jun 2011) $


1. Naming
General 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
{
   ...
}

2. Layout and comments
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.
  • All comments should be in English.
  • Do not start each line of a comment with a star
More info about Javadoc can be found at: http://java.sun.com/j2se/javadoc/writingdoccomments/index.html
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:
  • @author (first name of author(s))
  • @version 2.0
  • optionally, add any relevant @see tags
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:
  • @param: One tag for each parameter of the method. Make sure to tell what values are allowed and what will happen if a disallowed value is passed.
  • @return: What is returned by the method. Make sure to tell what values can be returned (ie. if it can be null).
  • @throws: List each exception that the method can throw and describe when and why it is thrown.
  • @see: If there are any relevent information.
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
  • All comments should be in English.
  • Comment on why instead of what. Your code should be clear enough to answer questions on what it does. It is more important to document why it does it.
  • Do not place end line comments at the end of statements.
  • Do not use decorated banner like comments, as these are hard to maintain. If more extensive commenting is needed - use Javadoc.
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 5673 2011-06-27 12:06:13Z nicklas $

	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 BASE. If not, see .
*/

3. Statments
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:

  1. project specific packages
  2. bioinfo internal packages
  3. third party packages
  4. java package
  5. javax package

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:
  • public static final attributes
  • other static attributes
  • public static methods
  • other static methods
  • private attributes
  • constructors
  • Methods defined by interfaces, grouped by the interface in which they are defined
  • Methods that override a method from a superclass, with methods from the topmost superclass first
  • Additional methods for the specific class
Classes and interfaces Class and interface statements should be organizied in the following manner:
  • class or interface statement
  • extends statement indented on a separate row
  • implements statement indented on one or more rows
  • class body
Examples: 
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
  • There must always be braces around the block following the condition control structure, even if it's just a single statement block. This doesn't apply to the cases when the single statement is on the same line as the condition.
  • Avoid placing statements resulting in side effects (e.g. function calls) in the condition construct.
  • Do not jump out of conditional blocks with break, return or exit. The exception is the usage of break in switch-statements.
  • Use continue-statements in for- and while- loops with caution. It's recommended to mark the statement with a clear comment.
Examples: 
// IF-statements:
if (...)
{
��� ...
}
else
{
��� ...
}

// FOR-statements:
for (init; condition; update)
{
�� ...
   /* #### CONTINUE-STATEMENT #### */
   continue;
}

// 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
{
�� ...
}