OpenSubsystems

Business Components for Java Applications

Documentation

Coding
Conventions

Last modified

$Author: bastafidli $
$Date: 2007/01/07 06:15:30 $
$Revision: 1.16 $
$RCSfile: codingconventions.html,v $

Introduction

Hoping that OpenSubsystems community will grow and many contributors will get involved, I feel it is desirable to set some recommendation how to write code for this project. These are just recommendation and not rules since any contribution to this project is more than welcome and won't be excluded. The main desire is to agree on a style, which makes the work with the code more pleasant so that anybody familiar with one part of the code can go to another module and immediately feel comfortable with the way the code is written.

To verify compliance with the coding conventions described below, OpenSubsystems uses Checkstyle to perform series of checks for the source code. The checkstyle configuration file you import to Checkstyle plugin for your favorite IDE or editor is located in

\sources\build\checkstyle.xml
               

Following rules were agreed upon by the original authors of the OpenSubsystems code. We are following Sun's coding conventions for Java language with following modifications:

2 - File Names

2.2 Common File Names
File names always have to have extension therefore you should use readme.txt for readme file. Otherwise users on Windows will be loosing time since they will never open the file directly with doubleclick, only using "Open With..." dialog, which takes forever to come up

3 - File Organization

3.1.1 Beginning Comments

/*
 * Copyright (c) 2003 - 2007 OpenSubsystems s.r.o. Slovak Republic. All rights reserved.
 * 
 * Project: OpenSubsystems
 * 
 * $Id: codingconventions.html,v 1.16 2007/01/07 06:15:30 bastafidli Exp $
 * 
 * This program 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; version 2 of the License. 
 * 
 * This program 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 
 */
               

4 - Indentation

The unit of indentation is 3 spaces. Set your editor to convert tabs to spaces. If you use tabs, and somebody else has his editor set differently, all you formatting is messed up.

4.2 Wrapping Lines
Use this indentation

//USE THIS INDENTATION INSTEAD
if ((condition1 && condition2)
   || (condition3 && condition4)
   ||!(condition5 && condition6))
{
   doSomethingAboutIt();
}
               

5 - Comments

Every class, method and variable has to have javadoc comments. Comments should explain use, assumption and any other thing, which are only in your head but should be known to other (usually why you did the things the way you did, how are they used, etc.). Without comments other developers will loose their time trying to read the code and figure out what you have meant by it. They will still need to read the code to understand it and see if it does what you described in your comments it does, but at least they have a hint before they start.

6 - Declarations

6.1 Number Per Line
Only one declaration per line is allowed. This way is very easy to see in a diff tool what have been changed. Also when we change the type for one variable, it doesn't automatically change it for the other ones as well (which could be be wrong).

6.3 Placement
NEVER declare variables inside of loop. It has performance impact since Java is slow in allocating and dealocating variables. Declare variables outside of loop and then use them inside. If you need to reset them to a default value, do so at the beginning of the loop.

6.4 Class and Interface Declarations
Methods has to be declared with each parameter and each exception on a new line. This way is very easy to see in a diff tool what have been changed and add new parameters or exceptions.

/**
 * javadoc here
 */
private void methodFoo(
   int    paramA,
   float  paramB,
   Object paramC
)
{
   // body here
}

/**
 * javadoc here
 */
private double methodFee(
)
{
   // body here
}

/**
 * javadoc here
 */
private abstract double methodFee(
);
               

7 - Statements

7.2 Compound Statements
The curly bracket is always on a new line. There is never anything else on that line. Again, this improve readability of the code and helps in the diff tools to see changes.

if (foo)
{
   // code here
}

try
{
   // code here
}
catch (final Exception bar)
{
   // code here
}
finally
{
   // code here
}

while (true)
{
   // code here
}
               

7.3 return Statements
Try to have only one return statement per method. This helps you in the debugging when you want to watch return value from the function. It also makes the flow in the method more predictable and easier to understand.

7.4 if, if-else, if else-if else Statements
Based on 7.2 it looks like this

if (condition)
{
   statements;
}
else if (condition)
{
   statements;
}
else
{
   statements;
}

and even only one statement has curly brackets.

if (condition)
{
   statements;
}
               

7.5 for Statements
Based on 7.2 it looks like this

for (initialization; condition; update)
{
   statements;
}

//An empty statement has to have explnanation why it is empty
for (initialization; condition; update);
               

7.6 while Statements
Based on 7.2 it looks like this

while (condition)
{
   statements;
}
               

7.7 do-while Statements
Based on 7.2 it looks like this

do
{
   statements;
}
while (condition);
               

7.8 switch Statements
Based on 7.2 it looks like this

switch (condition)
{
   case ABC:
   {
      statements;
      /* falls through */
   }

   case DEF:
   {
      statements;
      break;
   }

   case XYZ:
   {
      statements;
      break;
   }

   default:
   {
      statements;
      break;
   }
}
               

7.9 try-catch Statements
Based on 7.2 it looks like this

try
{
   statements;
}
catch (ExceptionClass e)
{
   statements;
}
finally
{
   statements;
}
               

8 - White Space

8.2 Blank Spaces
Casts don't have to be followed by a blank space. Examples:

myMethod((byte)aNum, (Object)x);
               

9 - Naming Conventions

NEVER use one character variables, such as i, j, k. Use for example iIndex1, iIndex2 or just index1, index2. If you use one letter variable it is more difficult to rename them and search for them (even though Eclipse does a pretty good job with refactoring), since less capable tools would pick even other instances where these letters appear. All static variables start with s_ prefix, e.g. s_iInstanceCounter; All member variables start with m_ prefix, e.g. m_valueList; Use selfexplanatory names.

10 - Programming Practices

10.5.2 Returning Values
Try to have only one return statement per method. This helps you in the debugging when you want to watch return value from the function. It also makes the flow in the method more predictable and easier to understand.

10.5.4 Special Comments
Use the following to mark places which needs to be looked at. Tools such as Eclipse and Checkstyle supports displaying of these markers during build process.

// TODO: comments
               

Use your name or other identifiers to categorize the type of TODO, for example:

// TODO: For John Doe: comments which john should do
// TODO: Performance: comments what to do to improve performance in the future
// TODO: Improve: comments how to improve code in the future
// TODO: Bug yyy #xxx: comments about workaround for bug xxx in library yyy
// TODO: Config: comments what to make configurable
// TODO: Test: comments what to write test for
               

11 - Code Examples

11.1 Java Source File Example
TODO: Modify headers

/*
 * Copyright (c) 2003 - 2007 OpenSubsystems s.r.o. Slovak Republic. All rights reserved.
 * 
 * Project: OpenSubsystems
 * 
 * $Id: codingconventions.html,v 1.16 2007/01/07 06:15:30 bastafidli Exp $
 * 
 * This program 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; version 2 of the License. 
 * 
 * This program 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 java.blah;

import java.blah.blahdy.BlahBlah;

/**
 * Class description goes here.
 *
 * @version    1.82 18 Mar 1999
 * @author  Firstname Lastname
 */
public class Blah extends SomeClass
{
   /* A class implementation comment can go here. */

   /**
    * classVar1 documentation comment
    */
   public static int s_classVar1;

   /**
    * classVar2 documentation comment that happens to be
    * more than one line long
    */
   private static Object s_classVar2;

   /**
    * instanceVar1 documentation comment
    */
   public Object m_instanceVar1;

   /**
    * instanceVar2 documentation comment
    */
   protected int m_instanceVar2;

   /**
    * instanceVar3 documentation comment
    */
   private Object[] m_instanceVar3;

   /**
    * ...constructor Blah documentation comment...
    */
   public Blah(
   )
   {
      // ...implementation goes here...
   }

   /**
    * ...method doSomething documentation comment...
    */
   public void doSomething(
   )
   {
      // ...implementation goes here...
   }

   /**
    * ...method doSomethingElse documentation comment...
    * @param someParam description
    * @throws Exception1
    * @throws Exception2
    */
   public void doSomethingElse(
      Object someParam
   ) throws Exception1,
            Exception2
   {
      // ...implementation goes here...
   }
}