iWombat.com

Java Coding Style Guidelines

Table of Contents

Naming Conventions

Package Names
Class and Interface Names
Method Names
Attribute and Local Variable Names
Arrays vs Lists
Don't "Hide" Names

Usage Conventions

Class Attributes
Modifier Usage
Class and Package Imports
Methods
Keep it Simple
Place Constants on Left Side of Expressions
Optimization vs Abstraction

javadoc

Overall Guidelines
Method Documentation
Use the @deprecated Tag

Naming Conventions

Package Names

Following a developing, de-facto standard in the Java world, all packages should be prefixed with: "com.iwombat"

Further subdivision is up to the individual project teams. In the case of common code, reusable components will be placed within a package named according to the component, such as "com.iwombat.security" or "com.iwombat.ui". Business objects will be segregated by business domains, or product offerings, as appropriate.

Package names should always be expressed in lowercase. In the event that multiple words are used to define a level in the package naming hierarchy, these words should be run together with no separating space or other character. Abbreviations can be used if they are commonly used, i.e. ui for user interface. An incorrect package name would be "com.iwombat.user_interface" due to the separating character between "user" and "interface".

Class and Interface Names

Class names are always nouns, not verbs. Avoid making a noun out of a verb, example DividerClass. If you are having difficulty naming a class then perhaps it is a bad class.

Interface names should always be an adjective (wherever possible) describing the enforced behaviors of the class (noun). Preferably, said adjective should end in "able" following an emerging preference in Java. i.e. Clonable, Versionable, Taggable, etc.

Class, and interface names begin with an uppercase letter, and shoule not be pluralized unless it is a collection class (see below).

Naming collection classes (in the generic sense of collection) can be tricky with respect to pluralization. In general each collection should be identified as a plural item, but not redundantly so. If you are a collection type as part of the class name (List, Map, etc.) it is not necessary to use the plural form in the class name. If you are not using the collection type in the name it is necessary to pluralize the name. If you are extending one of the java colletction class (Map, HashMap, List, ArrayList, Collection, etc.) it is good practice to use the name of the collection type in the class name.

Class names should be descriptive in nature without implying implementation. The internal implementation of an object should be encapsulated and not visible outside the object. Since implementation can change, to imply implementation in the name forces the class name and all references to it to change or else the code can become misleading.

Method Names

Method names are typically verbs. However they can also be nouns for example accessor methods (see accessor methods below). In general, when a method modifies the object (or a related object) somehow use a verb appropriate to the nature of the modification. i.e. set, free, sort etc. If the method is an accessor method use a noun appropriate to the information that is returned.

Strive for names that promote self documenting code. The method name should read well in the code. Picture how the method will appear in your code.

Method and function names begin with a lowercase letter. The initial letter of any subsequent words in the name are capitalized, and underscores are not used to separate words.

Attribute and Local Variable Names

Do not use abbreviations, use full names. Variable names begin with a lowercase letter. The initial letter of any subsequent words in the name are capitalized, and underscores are not used to separate words (or scope variables). Clarity of variable names can be increased by providing some indication of the type of class they might become. Attributes that are not collections should not be pluralized.

Name variables with the most abstract class that they can hold. For example if startButton could be any control object, then it should be named a startControl .

If the variable truly represents an anonymous object but is restricted by an interface, then including the interface name in the variable can increase clarity. i.e. clonableInventoryItem .

Declare each variable separately on a single line. Do not comma separate variables of the same type.

Constant values should have uppercase letters for each word and each word should be separated by an underscore. The capitalization of constants helps to distinguish them from other nonfinal variables.

Returning Arrays and Lists

Any method that will returns an list of homogeneous or heterogeneous items should return a Collection (or other collection class) object -- never an array.

Example: for a method that returns a list of keys represented as strings.

Also, any method that returns a Collection should always return a valid Collection -- never null. However, the returned Collection can be empty.

Don't "Hide" Names

Name hiding refers to the practice of naming a local variable, argument, or field the same (or similar) as that of another of greater scope. For example, if you have a class attribute called firstName do not create a local variable called firstName or anything close to it, such as firstNames or fName. Try to avoid this, it makes you code difficult to understand and prone to bugs because other developers will misread your intentions and create difficult to detect errors.

---

Usage Conventions

Class Attributes

Class attributes should always be accessed through accessors and mutators (getters and setters). Accessors and mutators are methods used to return and set the attribute value. These methods typically begin with "get" or "set", followed by the attribute name. As with other methods, the first letter of the method name should be in lowercase.
Note: Boolean accessors typically begin with "is" i.e. isFixed(), and return a Boolean value.

Example:

Attribute(s):
   int useCounter;

Getter:
   int getUseCounter(){
      return useCounter;
   }

Setter(s):
   void setUseCounter(int count){
      useCounter = count;
   }

   void incrementUseCounter() {
      setUseCounter(getUseCounter()+1);
   }

   void decrementUseCounter() {
      setUseCounter(getUseCounter()-1);
   }

Be safe and initialize all local variables at creation and all class attributes in the constructor(s)!

Modifier Usage

Class and Package Imports

   com.iwombat.ui.winnt.CDPlayer aPlayer = new com.iwombat.ui.winnt.CDPlayer();

then all those references would have to change when you port to UNIX. However, if the class is referenced as below:

   import com.iwombat.ui.winnt.CDPlayer;
   CDPlayer aPlayer = new CDPlayer()

Then changing to UNIX simply requires importing com.iwombat.ui.unix.CDPlayer instead.

Imports should be done on specific classes only. Imports should not include entire packages.

Methods

Methods in well-designed object-oriented code are short. Strive to keep methods less than 10 lines. Reconsider methods that are over a page in length, breaking them into several methods representing smaller blocks of functionality.

Break up long methods into small methods. This promotes code reuse and allows for more combinations of methods. If the number of methods grows to be difficult to understand, then look at decomposing the class into more than one class.

Follow the 30-second rule. Another programmer should be able to look at your method and fully understand what it does, why it does it and how it does it in less than 30-seconds. If that is not possible, then your code is too complex and difficult to maintain. A good rule of thumb is that a method should be no more than a screen in length.

Keep it simple

Avoid nesting method calls too deeply, since this can introduce undue complexity.

Avoid using compound predicates:

Place Constants on Left Side of Comparisons

1.    if (something == 1) { ... }
      if (x = 0) { ... }


2.    if (1 == something) { ... }
      if (0 = x) { ... }

Optimization vs Abstraction

---

Javadoc Conventions

Included in sun's JDK is a documenting tool called javadoc that processes Java source code files and produces external documentation in the form of html files. Javadoc is a great utility, but it does have limitations. Javadoc supports a limited number of tags -- learn them and use them well. The following is a general guideline for commenting your code to support javadoc.

Overall Guidelines

• Document What code does as well as why it was developed. For example, youcan look at a piece of code, or class and figure out what it does internally. However, it may not exactly be apparent what requirements, or other systems this class supports or, why the code is trapping for and throwing certain exceptions.
• Document difficult or complex functionality
• Document dependencies, if methods call other methods internally it is important to note that in the method description.
• Document members of the Domain Object Model that your class is based on, or inspired by.
• Methods that implement an interface should not provide javadoc comments, since the javadoc comments are included in the interface and will be referenced when javadoc executes.

Standard .java file header

Method Documentation

Each method should include the @exception, @param, and @return javadoc tags where appropriate.

Use the @deprecated Tag

In general it is not a good idea to remove methods from a class (or classes from a package), instead label old methods with the @deprecated tag. With liberal use of this tag you are less likely to break builds and code in use elsewhere. However, the compiler will produce warnings letting other developers know that they are using a deprecated method (or class).

Acceptable: