The following sections define the conventions Sun is looking for. There is some flexibility, but don't stray too far from these recommendations. NamesJava 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.
These are the most popular capitalizing conventions for identifiers:
Source Code and Class FilesJava 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 . PackagesPackage 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 StatementsPlace 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.
ClassesClass 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 . MethodsUnlike 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 ParametersFields (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; } ConstantsConstants 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). IndentingI 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); } }
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. |