Java coding guidelines

Satya - Friday, August 19, 2005 4:32:58 PM

Write your java classes inside packages

Specify a package name for your java classes. This typically looks lik

package com.ai.aspire;
public class SomeDataStructure
{
}

Satya - Friday, August 19, 2005 4:34:46 PM

Name your packages in lower case

It has been a common practice to name your packages in lowercase. I haven't seen mixed case that much.

Satya - Friday, August 19, 2005 4:35:48 PM

Name your classes Capitalized

It is also common practice to have the classnames starting with an upper case and move to a mixed case then on. Example

String
Vector
List

Satya - Friday, August 19, 2005 4:38:24 PM

Put comments on what your class does

It is very useful to say something about the class and what its role is. Unless we are naming experts it is hard to grasp what the class does solely based on its name. It is nice if it does. But we can't depend on it.

Example

package com.ai.aspire;
/**
* This class is responsible for something
* It does this. does this etc.
*/
public class SomeDataStructure {}

Satya - Friday, August 19, 2005 4:39:51 PM

Method names start lowercase and mixed case

Method names start with a lowercase and then proceed to mixed case on a new word boundary. Again this is just a convention

Satya - Friday, August 19, 2005 4:44:37 PM

Method body and the try block

When you are writing a method, sometimes you have the entire method body encapsulated in a single big try block. If the length of this block is more than 10 to 15 lines, think of writing a another function that does a throw of the most of the stuff and call that function through the main method. That way you have a place to deal with your errors unconfusing your main line logic.

Provide an example.

Satya - Friday, August 19, 2005 4:45:54 PM

Please give symbolic names for your variables.

Although "temp", "i", "k" are all valid variables under some circumstances, make their names more meaningful if you can.

Satya - Friday, August 19, 2005 4:47:02 PM

Keep your method body small

Try to keep your method body to with in 15 to 20 lines where applicable.

Satya - Friday, August 19, 2005 4:49:54 PM

Eliminate elses in a waterfall

If your method has some exclusion conditions that you want to avoid before getting to the main part you can use the following pattern

if (cond1)
{
   do something and return;
}
if (cond2)
{
   do something and return;
}

//Here is the main logic
do something

This is easier to read than putting an if and else around the whole thing. It is difficult follow the chain in that case.

Satya - Friday, August 19, 2005 4:53:33 PM

Rethrow exceptions

Please don't swallow exceptions. This will make it very hard to debug in maintenance mode.

catch(RequestExecutionException x)
{
   throw new DBException("Error message",x);
}

See how an exception is converted into another one and retrhown. The following is not right

catch(RequestExecutionException x)
{
   //do nothing and dupe the compiler
}

Satya - Friday, August 19, 2005 5:01:16 PM

Make sure you close your resources in a finally clause

As you work with resources such as database cursors or connections make sure you close them before leaving your functions. Only way to accomplish this is to do them in the finally clause.

Satya - Friday, August 19, 2005 5:02:38 PM

You may have to reorg your code around resource usage

Especially when your function uses database cursors in various for loops, it gets odd to close collections. In that case reorg your code into multiple functions so that each function handles one set of resource usage.

Satya - Friday, August 19, 2005 5:25:47 PM

Try not to run after your own tail

function() {
 try {
    throw SomeTypedException();
 }
 catch (SomeTypedException x) {
 }
}

Satya - Saturday, August 20, 2005 12:08:41 AM

Post fix your names for what they are: Or call a list a list if it is a list

Prefer

List columnValuesList;

to

List columnValues;

satya - 10/4/2014 11:02:02 AM

Refactor your code often to move classes to their correct packages

Make sure classes belong to the package that they are in.

satya - 10/4/2014 11:07:37 AM

Document packages in Java

Document packages in Java

Search for: Document packages in Java

Use package-info.java to do this


//package-info.java
/**
* Comments
*/
package com.foo;
//Thats all

satya - 10/4/2014 11:11:53 AM

Here is an example


/**
 * This package contains driver classes to test the 
 * direct SQL access in Android.
 * 
 * These classes use the interface based persistence services
 * from the com.androidbook.provider.services package.
 *
 * These actual services are implemented in the package
 * com.androidbook.provider.services.impl.sqlite
 */
package com.androidbook.provider.directaccess;

satya - 10/4/2014 11:14:51 AM

So, make sure packages are documented

So, make sure packages are documented

satya - 10/4/2014 11:14:57 AM

Make sure classes are documented

Make sure classes are documented

satya - 10/4/2014 11:15:46 AM

However, Keep the documentation brief, and specific

However, Keep the documentation brief, and specific

satya - 10/4/2014 3:02:19 PM

Find a better way to document a cluster of related classes in a given package

These classes use each other. Ideally every class has a reference to the others and what they do. They collectively does something useful. May be give them their own package. But sometimes that is an overkill.