Naming Conventions

More than anything else, names give meaning to code. I recommend telling a little story with your code. The nouns are the variable names, and the verbs are the method names . The following example uses a fictitious situation, but it illustrates the point:

English:

 Jack and Jill went up the hill, To fetch a pail of water; 

Java:

 public class JackJillStory {     String maleActor = "Jack ";     String femaleActor = "Jill ";     String pailContents = "empty ";     String location = "hill ";     String direction = "went up ";     String story = "";     public static void main(String[] args)     {         JackJillStory jackNjill = new JackJillStory();         jackNjill.fillPail("water");         jackNjill.story = jackNjill.getStory();         jackNjill.tellStory(jackNjill.story);     }     void tellStory(String story)     {             System.out.println(story);     }     String getStory()     {             String tale = maleActor                          + femaleActor                          + direction                          + location                          + "to fetch a pail of "                          + getPail();             return tale;     }     void fillPail(String contents)     {             pailContents = contents;     }     String getPail()     {             return pailContents;     } } 

This example clearly demonstrates how good use of names tells a story. In real life, other people should be able to read your code like a story, even if it is obscure poetry.

Table 4.1 offers good examples of how to follow standard Java naming conventions for the main items in Java that need a name , including the package, classes, methods , method parameters, and fields. These names are from the J2SE 1.4 Software Development Kit (SDK) source code.

Table 4.1. Good Examples of Identifier Names

Code Item	Example	Purpose
Package	java.util.logging	These classes and interfaces compose Java's core logging facilities.
Class	Level	The Level class defines a set of standard logging levels that can be used to control logging output. There are logging Level objects that are ordered and specified by ordered integers. Enabling logging at a given level also enables logging at all higher levels.
Method	getLocalizedName()	Return the localized string name of the Level object (mentioned previously) for the current default locale.
Method parameter	Level(String name, int value, String resourceBundle Name)	A constructor that creates a named Level object with a given integer value and a given localization resource name.
Field	SEVERE	This message level indicates a serious failure.

The following example is adapted from the Level class in the J2SE 1.4 SDK and demonstrates how to use good names and comments throughout. It is the same class that provided the preceding name examples. Most of the source code in the SDK is done professionally, as shown in the following example. I removed much of the code for space reasons, but you can see how clear this class is and how well it is commented. Although the following code is incomplete and will not compile, I recommend running javadoc against it and looking at the resulting documents.

 /*  * @(#)Warning.java    1.10 3/21/2003  *  * Copyright blah blah  */ package mypackage; import java.util.ResourceBundle; /**  * The Warning class defines a set of warning levels that  * can be used to for event monitoring.  * <p>  * Normal usage is:Warning.SEVERE.  *  *  * @version 1.10, 02/25/02  * @since 1.4  */ public class Warning implements java.io.Serializable {     private static java.util.ArrayList known = new java.util.ArrayList();     private static String defaultBundle = "sun.util.logging.resources. logging";     /**      * SEVERE is a warning level indicating a serious failure.      * <p>      * In general, SEVERE messages should describe events that are      * of considerable importance and that will prevent normal      * program execution. They should be reasonably intelligible      * to end users and to system administrators.      * This Warning is initialized to <CODE>1000</CODE>.      */     public static final Warning SEVERE = new Warning("SEVERE",1000, defaultBundle);     /**      * Create a named Warning with a given integer value and a      * given localization resource name.      * <p>      * @param name the name of the Warning, for example "SEVERE".      * @param value an integer value for the Warning.      * @param resourceBundleName name of a resource bundle to use in      *    localizing the given name (can be null).      */     protected Warning(String name, int value, String resourceBundleName) {         this.name = name;         this.value = value;         this.resourceBundleName = resourceBundleName;         synchronized (Warning.class)         {             known.add(this);         }     }     /**      * Return the localized string name of the Warning for      * the current default locale.      * <p>      * If no localization information is available, the      * non-localized name is returned.      *      * @return localized name      */     public String getLocalizedName()     {         try         {             ResourceBundle rb = ResourceBundle.getBundle(resourceBundleName);             return rb.getString(name);         } catch (Exception ex)         {             return name;         }     }     /**      * Generate a hashcode.      * @return a hashcode based on the Warning value      */     public int hashCode()     {         return this.value;     } } 

Unfortunately, many candidates get overzealous and comment everything. You will lose points if you do this, however.