Java coding standards

I've been coding in Java for some time now and I've found that it's very useful to have common coding standards amoung those that you work with. So I've listed some coding standards that I expect others to follow when writing Java code. I've found that it's rather useful to always write as if the code will be used in production, because eventually it will (wether you like it or not).

Coding standards are important because they can make the code easier to read and quickly figure out what's going on. An example of this is how variables are named. If a group all agrees that class variables are named one way and local variables are named another way, one can instantly tell if a line of code just effects state in the local scope or if it effects state in the class scope. These coding standards are also in place to help out with common coding errors, such as adding a line of code after an if statement without an explicit body causing the if statement to execute a whole difference piece of code.

Start with the "Draft Coding Standard" by Doug Lea, The idea of making all methods synchronized doesn't really make sense though, so skip that one.

General coding conventions:

Some of these are repeast of the document from Doug Lea (above), but these are ones I want to highlight.

• Use Ant for builds. This way everyone will have the same build and run environments. And this build environment is platform independent, since Ant is written in Java. Furthermore use checkstyle to enforce most of these coding conventions. An example checkstyle_checks.xml is available here. Ant is also used for generating javadoc documentation and building distributions. Each project I've setup has a build.xml file at the top of the source tree with all of this setup.
• Naming conventions:
  • instance variables - start with 'm' then an upper case letter. The 'm' isn't really required with a good IDE, but it's helpful to have.
  • local variables - start with a lower case letter
  • method names - start with a lower case letter
  • class & interface names - start with an uppercase letter
  • package names - start with a lower case letter
  • public static final variables, constants - all upper case
• Keep the code platform and system independent
  • Use relative paths.
  • Use getResource() or getResourceAsStream() rather than file paths to find resources in the program. This way the code will continue to work when distributed as a jar.
  • Use pure Java, avoid exec calls and native methods.
  • Create shell AND batch files where needed. These should be generated with Ant to handle system configuration changes.
• Use anynomous listeners. This makes it easier to find what happens when events happen. Public listeners are required for voyager when listening from client to server, this is the only exception.
• Don't use outer classes. These are classes that exist in the same file as another class, but aren't inside that classes' enclosing braces. Make them inner classes, or create a separate file for them. There are some odd protection issues involved with outer classes.
• When using inner classes, make them static where possible. This reduces the amount of memory taken up by classes.
• Make method parameters final. This avoids assignment to the parameters and expecting the data to change where the method was called from.
• Make variable declarations final if possible. This make reading code much easier, since you can tell quickly which variables are dynamic.
• Use javadoc comments. Document everything! This makes it easier to determine later why a method was written or a variable was added. This also gives us an easy way to produce separate documents that describe the application and it keeps the documents up to date. See Javadoc Guidelines for more information.
• Avoid protected and package visability. Stick with public and private if possible. They lead to cleaner interfaces. There are places where package and protected visibility are required, but make sure you know exactly what these modifiers mean and only use where required. In many cases these modifiers should be used with the final modifier.
• Make all data private unless required for performance and then only package.
• Put braces around the bodies of all if/else bodies. This makes the code tremendously easier to read. It also leaves no confusion as to which else belongs to which if when nesting. Braces go after the condition in if statements like so:

  if(condition) {
    body
  }
  Not
  if(condition)
  {
    body
  }
          

• Don't import things you don't need! Don't use star imports or leave imports hanging around that you don't need. There's a handy perl script I wrote to help with this here. Also many tools, such as checkstyle support checking for this and may IDEs can remove these star imports.
• Use nouns for package names. For example, editor instead of editing
• Use the singular form of nouns for package names. For example util instead of utils
• Wherever defining equals() you should also be defining hashCode() and vice versa. If equals is just delegating to another object, hashCode is pretty easy, just delegate hashCode as well. In other cases it gets more complicated, but can be done. Refer to the documentation of hashCode on java.lang.Object for more information.
• Use a logging package for output instead of System.out and System.err. This makes debugging much easier and allows one to configure multiple sources for output, even at runtime. Some logging packages are:
  • Commons Logging - good for building APIs as it allows users to pick the logging package to use
  • Log4j
  • Java Logging API - Sun added a logging API in JDK 1.4
• Avoid empty catch statements. They can hide exceptions that you need to handle. In cases where you really want to do nothing add a comment and a debug statement explaining why.
• Don't catch Exception, Throwable or RuntimeException. Except in extreme cases, such as when creating an application that needs to run for extended periods of time and cannot fail under any circumstances.
• Don't duplicate code. Wherever possible, reuse existing code or refactor to avoid duplication of code.
• Hide implementation details by using interfaces where possible instead of classes. This allows one class to implement multiple behaviors and modification of the backed easily without requring everyone's code to change, unless an API change is made.
• If there is a test target in the ant build file, use it before you check any code into source control. This will ensure your code is compatible with existing test cases.
• When working on web projects, avoid scriplets. Use JSTL and custom tags instead. Separate HTML and Java wherever possible.
• Use POST on all web forms to ensure we don't run into URL length problems.

References

Here are some other sources worth looking at:

• "Draft Coding Standard" by Doug Lea - However I don't agree with the idea of making all methods synchronized.
• Gwydion Style Guide for Java
• And of course if you are worried about job security, look at this: How To Write Unmaintainable Code