Convention Preferences

The following sections define the conventions Sun is looking for. There is some flexibility, but don't stray too far from these recommendations.

Names

Java programs have a lot of names (also called "identifiers"). The biggest goof I see in my student's code, and my earlier work, is lack of description. You don't have to write a sentence , but getCustomerID() is more descriptive than getInt() . This is how you should use descriptive names in your source code.

In names, avoid acronyms and abbreviations unless they are already well known, such as "XML" or "JSP."

These are the most popular capitalizing conventions for identifiers:

• Pascal ” The first letter of the identifier and the first letter of each subsequent concatenated word are capitalized. Name classes using the Pascal convention. A few examples are Customer , NewCustomer , and PremiumCustomer .

• Camel ” The first letter of an identifier is lowercase, and the first letter of each subsequent concatenated word is capitalized. Name variables and methods using the camel convention. A few examples are getFirstName() , isLocked() and myCollection .

• Uppercase ” All letters are in uppercase. Name constants using all uppercase letters . A few examples are QUOTE , SPACE , and TAB String constants.

• Lowercase ” All letters are in lowercase. Name one-word variables and methods using all lowercase letters. Packages should be all lowercase as well. A few examples are com.mycompany.mypackage , first_name and remove() .

Source Code and Class Files

Java source files always use the .java suffix. The filename is always the same as the class declaration name, including the name's letter case. The Customer class, for example, has a source filename of Customer.java and a compiled name of Customer.class .

Packages

Package naming has been influenced by the Internet. The prefix of a unique package name is always written in all-lowercase ASCII letters. Although this practice isn't necessary, you can use one of the top-level domain names (for example, com, edu, gov; consult World Wide Web Consortium "Web Naming and Address" page at http://www.w3.org/Addressing/), as in edu.vanguard.library . The idea is to eliminate the possibility of someone duplicating your package name, so using a top-level name gives you a better chance of having a unique package name.

Import Statements

Place your import statements at the top of the page, immediately after the package declaration. Try to be explicit in your import declarations and avoid using the wildcard character. When all the classes are listed in the import section, it clearly indicates what classes are used in the subsequent code.

Use explicit imports, such as import a.b.ThisThing; . Try to avoid implicit imports using the wildcard character, like so:

 import a.b.*; 

Classes

Class names should be mixed-case nouns, with the first letter of each word capitalized (for example, RandomAccessFile , not randomaccessfile ). These names should be short, but still descriptive. For example, a class for addresses should be Address , not Addr .

Methods

Unlike classes, which have names that are a combination of nouns, methods use a combination of an action verb and noun. For example, the method to return the customer ID in a system should be getCustomerID() . There is a little debate here about combining the class name and method name. For example, which is better: Customer.getCustomerID() or Customer.getID() ? I prefer the former, but whichever you use, stay consistent. Methods that return a Boolean value often begin with is , such as isDBLocked() . Regarding get/set syntax, start with get/set , then capitalize each subsequent word like so: getFirstName() .

Fields, Variables, and Parameters

Fields (also known as "instance variables") and local variables should be declared at the beginning of the block. Use descriptive names that follow the camel case convention (see the definition in the "Names" section earlier in this chapter). Use descriptive nouns for parameters as well. In some cases, you can use short names, but describe the parameters in comments.

For example, in the following method declaration, the parameters are descriptive because the body of the method is long:

 /**  * Returns the customer name based on the ID.  *  * @param      customerID   the customer ID to filter.  */ String getCustomerName(int customerID) {       //many lines of code         ... } 

However, for the following example, the parameter names are short because the method is short and easier to manipulate:

 /**  * Returns the sum.  *  * @param      x   the first number.  * @param      y   the second number.  */ String getSum(int x, int y) {       //few lines of code         return x + y; } 

Constants

Constants should be named with nouns as variables are, but should consist of all uppercase letters, as in MAX_VALUE . As you probably know, the compiler doesn't care which convention you use (except that you must retain an identifier's spelling and letter case throughout a program). However, it makes your intentions clear when you spell constants in uppercase letters (for example, this variable will not change its value, so don't try to assign a value to it).

Indenting

I wrestled with the placement of the opening brace for some time. All the source code in the SDK and most of the Java community place the opening brace immediately after the method signature, on the same line as the block declaration. The following is an example of this convention:

 public class ClassCircularityError extends LinkageError {     public ClassCircularityError(String s) {     super(s);     } } 

Here's another common indenting method:

 public class ClassCircularityError extends LinkageError {     public ClassCircularityError(String s) {     super(s);     } } 

Should braces be placed around a single statement used as the body of a loop or a conditional? Although the syntax allows you to do that, it is safer to use the braces. Using this convention eliminates the common mistake of attempting to add a second statement to the if construct and not having it execute due to the absence of braces. Also, use one line for short conditional or loop expressions when it fits for clarity, like this:

 if (score == 100) { setGrade(name, "A");} 

However, I prefer the opening and closing brace to be aligned vertically for readability. The advantage of placing the opening brace immediately after the block declaration is there are no wasted lines and many people are used to this style. However, it is hard to match a closing brace with an opening one.

I once conducted a test on these two styles. As an adjunct professor at Vanguard University, I get plenty of students who have never written or seen a line of code. I wrote two code samples on the board that were identical except for the placement of the opening braces and asked them which style they preferred to read. The students who were completely new to programming rarely picked the sample with a brace at the end of a block declaration. I agree with these students, so I place the opening brace on the next line, directly under the first letter of the block declaration above it. It doesn't matter which style you use, however, as long as you use it consistently.