Java Programming Guidelines

Copyright © 1999 Scott Ambler, Ambysoft, Inc.

The Java Coding Guidelines are provided under license from Scott Ambler, Ambysoft Inc., www.ambysoft.com. They have been reformatted for inclusion in the Rational Unified Process.

Contents

1      Introduction
        1.1    The first and last guideline

2    Coding Standards
      2.1    Naming conventions
      2.2    Documentation conventions
              2.2.1  Types of Java comments
              2.2.2  A quick overview of javadoc   

3    Standards for Member Functions
      3.1    Naming member functions
              3.1.1    Naming accessor member functions
                         3.1.1.1    Getters
                         3.1.1.2    Setters
      3.2    Naming constructors
      3.3    Member function visibility
      3.4    Documenting member functions
               3.4.1    The member function header
               3.4.2    Internal documentation
      3.5    Techniques for writing clean code
               3.5.1    Document your code
               3.5.2    Paragraph or indent your code
               3.5.3    Use whitespace in your code
               3.5.4    Follow the 30-second rule
               3.5.5    Write short, single command lines
               3.5.6    Specify the order of operations

5    Standards for Local Variables
      5.1    Naming local variables
                  5.1.1    Naming streams
                   5.1.2    Naming loop counters
                   5.1.3    Naming exception objects
        5.2   Declaring and documenting local variables
               5.2.1     General comments about declaration

6    Standards for Parameters to Member Functions
      6.1    Naming parameters
      6.2    Documenting parameters
               6.2.1    Use interfaces for parameter types

7    Standards for Classes, Interfaces, Packages, and Compilation Units
      7.1    Standards for classes
                7.1.1    Naming classes
                7.1.2    Documenting a class
                7.1.3    Class declarations
                7.1.4    Minimize the public and protected interface
                            7.1.4.1    Define the public interface first
      7.2     Standards for interfaces
                7.2.1    Naming interfaces
                            7.2.1.1    Alternative
                7.2.2    Documenting interfaces
      7.3     Standards for packages
                7.3.1    Naming packages
                7.3.2    Documenting packages
      7.4     Standards for compilation units
                7.4.1    Naming compilations units
                7.4.2    Documenting compilation units

8    Error Handling and Exceptions

10    Patterns of Success
       10.1    Using these standards effectively
       10.2    Other factors that lead to writing successful code

11    Summary
        11.1    Java naming conventions
        11.2    Java documentation conventions
                   11.2.1    Java comment types
                   11.2.2    What to document
        11.3    Java coding conventions (general)

12    References

13    Glossary

1    Introduction

This document describes a collection of standards, conventions, and guidelines for writing solid Java code. They are based on sound, proven software engineering principles that lead to code that is easy to understand, to maintain, and to enhance. Furthermore, by following these coding standards your productivity as a Java developer should increase remarkably. Experience shows that by taking the time to write high-quality code right from the start, you will have a much easier time modifying it during the development process. Finally, following a common set of coding standards leads to greater consistency, making teams of developers significantly more productive.

1.1    The first and last guideline 

Use common sense. When you cannot find a rule or guideline, when the rule obviously does not apply, when everything else fails: use common sense, and check the fundamental principles. This rule overrides all of the others. Common sense is required.

2    Coding Standards

Coding standards for Java are important because they lead to greater consistency within your code and the code of your teammates. Greater consistency leads to code that is easier to understand, which means it is easier to develop and to maintain. This reduces the overall cost of the applications that you create.

You have to remember that your Java code will exist for a long time; long after you have moved on to other projects. An important goal during development is to ensure that you can transition your work to another developer, or to another team of developers so they can continue to maintain and enhance your work without having to invest an unreasonable effort to understand your code. Code that is difficult to understand runs the risk of being scrapped and rewritten.

2.1    Naming conventions

We will be discussing naming conventions throughout the standards, so let's set the stage with a few basics:

1. Use full English descriptors that accurately describe the variable, field, and class; for example, use names like firstName, grandTotal, or CorporateCustomer. Although names like x1, y1, or fn are easy to type because they're short, they do not provide any indication of what they represent and result in code that is difficult to understand, maintain, and enhance.
   
2. Use terminology applicable to the domain. If your users refer to their clients as customers, then use the term Customer for the class, not Client. Many developers make the mistake of creating generic terms for concepts when perfectly good terms already exist in the industry or domain.
   
3. Use mixed case to make names readable. Use lowercase letters in general, but capitalize the first letter of class names and interface names, as well as the first letter of any non-initial word. [KAN97]
   
4. Use abbreviations sparingly, but if you do so then use them intelligently. This means you should maintain a list of standard short forms (abbreviations), you should choose them wisely, and you should use them consistently. For example, if you want to use a short form for the word "number", then choose one of nbr, no, or num, document which one you chose (it does not really matter which one), and use only that one.
   
5. Avoid long names (< 15 characters is a good idea). Although the class name PhysicalOrVirtualProductOrService might seem to be a good class name at the time, this name is simply too long and you should consider renaming it to something shorter, perhaps something like Offering.
   
6. Avoid names that are similar or differ only in case. For example, the variable names persistentObject and persistentObjects should not be used together, nor should anSqlDatabase and anSQLDatabase.
   
7. Avoid leading or trailing underscores. Names with leading or trailing underscores are usually reserved for system purposes and should not be used for any user-created names. More importantly, underscores are annoying and difficult to type so try to avoid their use whenever possible.

2.2    Documentation conventions

We will also be discussing documentation conventions, so let's discuss some of the basics first:

1. Comments should add to the clarity of your code. The reason you document your code is to make it more understandable to you, your coworkers, and to any other developer who comes after you.
   
2. If your program is not worth documenting, it is probably not worth running. [NAG95]
   
3. Avoid decoration; that is, do not use banner-like comments. In the 1960s and 1970s, COBOL programmers got into the habit of drawing boxes, typically with asterisks, around their internal comments. Sure, it gave them an outlet for their artistic urges, but frankly it was a major waste of time that added little value to the end product. You want to write clean code, not pretty code. Furthermore, because many of the fonts used to display and print your code are proportional, and many are not, you can't line up your boxes properly anyway.
   
4. Keep comments simple. Some of the best comments are simple, point-form notes. You do not have to write a book; you just have to provide enough information so that others can understand your code.
   
5. Write the documentation before you write the code. The best way to document code is to write the comments before you write the code. This gives you an opportunity to think about how the code will work before you write it and will ensure that the documentation gets written. Alternatively, you should at least document your code as you write it. Because documentation makes your code easier to understand, you are able to take advantage of this fact while you are developing it. If you are going to invest the time writing documentation, you should at least get something out of it. [AMB98]
   
6. Document why something is being done, not just what. For example, the code in Example 1 below shows that a 5% discount is being given on orders of $1,000 dollars or more. Why is this being done? Is there a business rule that says that large orders get a discount? Is there a limited-time special on large orders or is it a permanent program? Was the original programmer just being generous? You do not know unless it is documented somewhere, either in the source code itself or in an external document.

Example 1:

if ( grandTotal >= 1000.00)

{

grandTotal = grandTotal * 0.95;

}

2.2.1    Types of Java comments

Java has three styles of comments: 

• documentation comments that start with /** and end with */
• C-style comments that start with /* and end with */
• single-line comments that start with // and go until the end of the source-code line

The following chart is a summary of a suggested use for each type of comment, as well as several examples.

Comment Type	Usage	Example
Documentation	Use documentation comments immediately before declarations of interfaces, classes, member functions, and fields to document them. Documentation comments are processed by javadoc, see below, to create external documentation for a class.	/** Customer: A customer is any person or organization that we sell services and products to. @author S.W. Ambler */
C style	Use C-style comments to document out lines of code that are no longer applicable, but that you want to keep just in case your users change their minds, or because you want to temporarily turn it off while debugging.	/* This code was commented out by B. Gustafsson on June 4, 1999 because it was replaced by the preceding code. Delete it after two years if it is still not applicable. . . . (the source code ) */
Single line	Use single line comments internally within member functions to document business logic, sections of code, and declarations of temporary variables.	// Apply a 5% discount to all // invoices over $1000 due to // generosity campaign started in // Feb. of 1995.

The important thing is that your organization should set a standard as to how C-style comments and single-line comments are to be used, and then to follow that standard consistently. Use one type to document business logic and use the other to document out old code. Use single-line comments for business logic because you can put the documentation on the same line as the code (this is called inlining). Use C-style comments for documenting out old code because that allows you to comment out several lines at once. Because C-style looks very similar to documentation comments, to avoid confusion don't use them elsewhere.

Beware Endline Comments-[MCO93] strongly argues against the use of inline comments, also known as endline comments or end of line comments. McConnell points out that the comments have to be aligned to the right of the code so they don't interfere with the visual structure of the code. As a result, they tend to be hard to format and "if you use many of them, it takes time to align them. Such time is not spent learning more about the code; it is dedicated solely to the tedious task of pressing the spacebar or the tab key." He also points out that endline comments are also hard to maintain because when the code on the line grows, it bumps the endline comment out and if you are aligning them, you have to do the same for the rest of them.

2.2.2        A quick overview of javadoc

Included in Sun's Java Development Kit (JDK) is a program called javadoc that processes Java code files and produces external documentation, in the form of HTML files, for your Java programs. Javadoc supports a limited number of tags; reserved words that mark the beginning of a documentation section. Please refer to the JDK javadoc documentation for further details.

Tag	Used for	Purpose
@author name	Classes, Interfaces	Indicates the author(s) of a given piece of code. One tag per author should be used.
@deprecated	Classes, Member Functions	Indicates that the API for the class has been deprecated and, therefore, should not be used any more.
@exception name description	Member Functions	Describes the exceptions that a member function throws. You should use one tag per exception and give the full class name for the exception.
@param name description	Member Functions	Used to describe a parameter passed to a member function, including its type or class and its usage. Use one tag per parameter.
@return description	Member Functions	Describes the return value, if any, of a member function. You should indicate the type or class and the potential use(s) of the return value.
@since	Classes, Member Functions	Indicates how long the item has existed; that is, since JDK 1.1.
@see ClassName	Classes, Interfaces, Member Functions, Fields	Generates a hypertext link in the documentation to the specified class. You can, and probably should, use a fully qualified class name.
@see ClassName#member functionName	Classes, Interfaces, Member Functions, Fields	Generates a hypertext link in the documentation to the specified member function. You can, and probably should, use a fully qualified class name.
@version text	Classes, Interfaces	Indicates the version information for a given piece of code.

The way that you document your code has a huge impact, both on your own productivity and on the productivity of everyone else who later maintains and enhances it. By documenting your code early in the development process, you become more productive because it forces you to think through your logic before you commit it to code. Furthermore, when you revisit code you wrote days or weeks earlier, you can easily determine what you were thinking when you wrote it because it's already documented for you.

3    Standards for Member Functions

Never forget that the code you write today may still be in use many years from now, and will likely be maintained and enhanced by somebody other than you. You must strive to make your code as "clean" and understandable as possible, because these factors make it easier to maintain and to enhance.

3.1    Naming member functions

Member functions should be named using a full English description, using mixed case with the first letter of any non-initial word capitalized. It is also common practice for the first word of a member function name to be a strong, active verb.

Examples:

openAccount()

printMailingLabel()

save()

delete()

This convention results in member functions whose purpose can often be determined just by looking at their names. Although this convention results in a little extra typing by the developer because it often results in longer names, this is more than made up for by the increased understandability of your code.

3.1.1    Naming accessor member functions

We will discuss accessors, member functions that get and set the values of fields (fields or properties) in greater detail in a next chapter. The naming conventions for accessors, however, are summarized below.

3.1.1.1    Getters 

Getters are member functions that return the value of a field. You should prefix the word "get" to the name of the field, unless it is a boolean field and then you prefix "is" to the name of the field instead of "get".

Examples:

getFirstName()

getAccountNumber()

isPersistent()

isAtEnd()

By following this naming convention, you make it obvious that a member function returns a field of an object, and for boolean getters you make it obvious that it returns true or false. Another advantage of this standard is that it follows the naming conventions used by the Beans Development Kit (BDK) for getter member functions. [DES97] The main disadvantage is that "get" is superfluous and requires extra typing.

A viable alternative, based on proper English conventions, is to use the prefix "has" or "can" instead of "is" for boolean getters. For example, getter names such as hasDependents() and canPrint() make a lot of sense when you are reading the code. The problem with this approach is that the BDK will not pick up on this naming strategy (yet). You could rename these member functions isBurdenedWithDependents() and isPrintable().

3.1.1.2    Setters

Setters, also known as mutators, are member functions that modify the values of a field. You should prefix the word "set" to the name of the field, regardless of the field type.

Examples:

setFirstName(String aName)

setAccountNumber(int anAccountNumber)

setReasonableGoals(Vector newGoals)

setPersistent(boolean isPersistent)

setAtEnd(boolean isAtEnd)

By following this naming convention, you make it obvious that a member function sets the value of a field of an object. Another advantage of this standard is that it follows the naming conventions used by the BDK for setter member functions. [DES97] The main disadvantage is that "set" is superfluous and requires extra typing.

3.2    Naming constructors

Customer()

SavingsAccount()

PersistenceBroker()

3.3    Member function visibility

For a good design where you minimize the coupling between classes, the general rule of thumb is to be as restrictive as possible when setting the visibility of a member function. If a member function does not have to be public, then make it protected, and if it does not have to be protected, then make it private.

Visibility	Description	Proper Usage
public	A public member function can be invoked by any other member function in any other object or class.	When the member function must be accessible by objects and classes outside of the class hierarchy in which the member function is defined.
protected	A protected member function can be invoked by any member function in the class in which it is defined, any subclasses of that class, or any classes in the same package.	When the member function provides behavior that is needed internally within the class hierarchy or package, but not externally.
private	A private member function can only be invoked by other member functions in the class in which it is defined, but not in the subclasses.	When the member function provides behavior that is specific to the class. Private member functions are often the result of refactoring, also known as reorganizing, the behavior of other member functions within the class to encapsulate one specific behavior.
default	By default (no visibility specified), a function can only be invoked by other member functions in the class in which it is defined, or any classes in the same package.	When the member function provides behaviour that is needed by classes within the same package, but not externally, and not by subclasses.

3.4    Documenting member functions

3.4.1    The member function header

Every Java member function should include some sort of header, called member function documentation, at the top of the source code that documents all of the information that is critical to understanding it. This information includes, but is not limited to, the following:

1. What and why the member function does what it does. By documenting what a member function does, you make it easier for others to determine if they can reuse your code. Documenting why it does something makes it easier for others to put your code into context. You also make it easier for others to determine whether or not a new change should actually be made to a piece of code (perhaps the reason for the new change conflicts with the reason why the code was written in the first place).
   
2. What member function must be passed as parameters. You also need to indicate what parameters, if any, must be passed to a member function and how they will be used. This information is needed so that other programmers know what information to pass to a member function. javadoc @param tag, discussed in section 2.2.2, A quick overview of javadoc, is used for this.
   
3. What a member function returns. You need to document what, if anything, a member function returns so that other programmers can use the return value or object appropriately. The javadoc @return tag, discussed in section 2.2.2, A quick overview of javadoc, is used for this.
   
4. Known bugs. Any outstanding problems with a member function should be documented so that other developers understand the weaknesses and difficulties with the member function. If a given bug is applicable to more than one member function within a class, then it should be documented for the class instead.
   
5. Any exceptions that a member function throws. You should document any and all exceptions that a member function throws so that other programmers know what their code will need to catch. The javadoc @exception tag, discussed in section 2.2.2, A quick overview of javadoc, is used for this.
   
6. Visibility decisions. If you feel that your choice of visibility for a member function will be questioned by other developers-perhaps you have made a member function public even though no other objects invoke the member function yet-then you should document your decision. This will help to make your thinking clear to other developers so that they do not waste time worrying about why you did something questionable.
   
7. How a member function changes the object. If a member function changes an object, for example the withdraw() member function of a bank account modifies the account balance, then this needs to be indicated. This information is needed so that other Java programmers know exactly how a member function invocation will affect the target object.
   
8. Avoid the use of headers containing information such as author, phone numbers, dates of creation and modification, and location of unit (or file name), because this information rapidly becomes obsolete. Place ownership copyright notices at the end of the unit. For instance, readers do not want to have to scroll through two or three pages of text that is not useful to the understanding of the program, nor do they want to scroll through text that does not carry any program information at all, such as a copyright notice. Avoid the use of vertical bars or closed frames or boxes, which just add visual noise and are difficult to keep consistent. Use a configuration management tool to keep unit history.
   
9. Examples of how to invoke the member function if appropriate. One of the easiest ways to determine how a piece of code works is to look at an example. Consider including an example or two about how to invoke a member function.
   
10. Applicable preconditions and postconditions. A precondition is a constraint under which a member function will function properly, and a postcondition is a property or assertion that will be true after a member function is finished running. [MEY88] In many ways preconditions and postconditions describe the assumptions that you have made when writing a member function [AMB98], defining exactly the boundaries of how a member function is used.
    
11. All concurrency issues. Concurrency is a new and complex concept for many developers and, at best, it is an old and complex topic for experienced concurrent programmers. The end result is that if you use the concurrent programming features of Java, then you need to document it thoroughly. [LEA97] suggests that when a class includes both synchronized and unsynchronized member functions, you must document the execution context that a member function relies on, especially when it requires unrestricted access so that other developers can use your member functions safely. When a setter, a member function that updates a field, of a class that implements the Runnable interface is not synchronized, then you should document your reason(s) why. Finally, if you override or overload a member function and change its synchronization, you should also document why.
    
12. You should document something only when it adds to the clarity of your code. You would not document all of the factors described above for each and every member function because not all factors are applicable to every member function. You would, however, document several of them for each member function that you write.

3.4.2    Internal documentation

3.5    Techniques for writing clean code

3.5.1    Document Your Code 

3.5.2    Paragraph or indent your code 

3.5.3    Use whitespace in your code 

A few blank lines, called whitespace, added to your Java code can help make it much more readable by dividing it into small, easy-to-digest sections. [VIS96] suggests using a single blank line to separate logical groups of code, such as control structures, with two blank lines to separate member function definitions. Without whitespace, it is very difficult to read and to understand.

3.5.4    Follow the 30-second rule 

3.5.5    Write short, single command lines 

3.5.6    Specify the order of operations 

4    Standards for Fields and Properties

4.1    Naming fields

You should use a full English descriptor to name your fields, [GOS96] and [AMB98], thereby making it obvious what the field represents. Fields that are collections, such as arrays or vectors, should be given names that are plural to indicate that they represent multiple values.

Examples:

4.1.1    Naming components (widgets)

For names of components (interface widgets), you should use a full English descriptor postfixed by the widget type. This makes it easy for you to identify the purpose of the component, as well as its type, which makes it easier to find each component in a list. Many visual programming environments provide lists of all components in an applet or application and it can be confusing when everything is named button1, button2, and so on.

Examples:

4.1.1.1    Alternative for naming components: Hungarian notation 

The "Hungarian Notation" [MCO93] is based on the principle that a field should be named using the following approach: xEeeeeeEeeeee where x indicates the component type and EeeeeEeeeee is the full English descriptor.

Examples:

The main advantage is that this is an industry standard common for C++ code so many people already follow it. From the name of the variable, developers can quickly judge its type and how it's used. The main disadvantages are that the prefix notation becomes

4.1.1.2    Alternative for naming components: postfix-Hungarian notation 

Basically this is a combination of the other two alternatives and it results in names such as okPb, customerLb, fileM, and newFileMi. The main advantage is that the name of the component indicates the widget type and that widgets of the same type are not grouped together in an alphabetical list. The main disadvantage is that you still are not using a full English description, making the standard harder to remember because it deviates from the norm.

4.1.1.3    Set component name standards 

Whatever convention you choose, you'll want to create a list of "official" widget names. For example, when naming buttons, do you use Button or PushButton, b or pb? Create a list and make it available to every Java developer in your organization

4.1.2    Naming constants

When fields are declared protected, there is the possibility of member functions in subclasses to directly access them, effectively increasing the coupling within a class hierarchy. This makes your classes more difficult to maintain and to enhance, therefore, it should be avoided. Fields should never be accessed directly; instead accessor member functions (see below) should be used.

Visibility	Description	Proper Usage
public	A public field can be accessed by any other member function in any other object or class.	Do not make fields public.
protected	A protected field can be accessed by any member function in the class in which it is declared or by any member functions defined in subclasses of that class.	Do not make fields protected.
private	A private field can only be accessed by member functions in the class in which it is declared, but not in the subclasses.	All fields should be private, and should be accessed by getter and setter member functions (accessors).

For fields that are not persistent (they will not be saved to permanent storage), you should mark them as either static or transient [DES97]. This makes them conform to the conventions of the BDK.

4.2.1    Do not "hide" names 

"Good program design seeks to isolate parts of a program from unnecessary, unintended, or otherwise unwanted outside influences. Access modifiers (accessors) provide an explicit and checkable means for the language to control such contacts." [KAN97]

Accessor member functions improve the maintainability of your classes in the following ways:

1. Updating fields. You have single points of update for each field, making it easier to modify and to test. In other words your fields are encapsulated.
   
2. Obtaining the values of fields. You have complete control over how fields are accessed and by whom.
   
3. Obtaining the values of constants and the names of classes. By encapsulating the value of constants and of class names in getter member functions when those values/names change you only need to update the value in the getter and not every line of code where the constant/name is used.
   
4. Initializing fields. The use of lazy initialization ensures that fields are always initialized and that they are initialized only if they are needed.
   
5. Reducing the coupling between a subclass and its superclass(es). When subclasses access inherited fields only through their corresponding accessor member functions, it makes it possible to change the implementation of fields in the superclass without affecting any of its subclasses, effectively reducing coupling between them. Accessors reduce the risk of the "fragile base class" where changes in a superclass ripple throughout its subclasses.
   
6. Encapsulating changes to fields. If the business rules pertaining to one or more fields change you can potentially modify your accessors to provide the same ability as before the change, making it easier for you to respond to the new business rules.
   
7. Simplifying concurrency issues. [LEA97] points out that setter member functions provide a single place to include a notifyAll if you have waits based on the value of that field. This makes moving to a concurrent solution much easier.
   
8. Name-hiding becomes less of an issue. Although you should avoid name hiding, giving local variables the same names as fields, the use of accessors to always access fields means that you can give local variables any name you want. You do not have to worry about hiding field names because you never access them directly anyway.

4.4.1.1    When not to use accessors 

The only time that you might want to not use accessors is when execution time is of the utmost importance. However, it's a very rare case when the increased coupling within your application justifies this action.

Getter member functions should be given the name "get" + field name, unless the field represents a boolean (true or false), and then the getter is given the name "is" + field name. Setter member functions should be given the name "set" + field name, regardless of the field type ([GOS96] and [DES97]). Note that the field name is always in mixed case with the first letter of all words capitalized. This naming convention is used consistently within the JDK and is required for beans development.

Examples:

Field	Type	Getter name	Setter name
firstName	string	getFirstName()	setFirstName()
address	Address object	getAddress()	setAddress()
persistent	boolean	isPersistent()	setPersistent()
customerNo	int	getCustomerNo()	setCustomerNo()
orderItems	Array of OrderItem objects	getOrderItems()	setOrderItems()

4.4.3    Advanced techniques for accessors

Accessors can be used for more than just getting and setting the values of instance fields. This section discusses how to increase the flexibility of your code by using accessors to:

• initialize the values of fields
• access constant values
• access collections
• access several fields simultaneously

4.4.3.1    Lazy initialization 

Variables need to be initialized before they are accessed. There are two schools of thought to initialization: Initialize all variables at the time the object is created (the traditional approach) or initialize at the time it's first used. 

The first approach uses special member functions that are invoked when the object is first created, called constructors. Although this works, it often proves to be error-prone. When adding a new variable, you can easily forget to update the constructors.

An alternative approach is called lazy initialization where fields are initialized by their getter member functions, as shown below. Note how a setter member function is used within the getter member function. Notice that the member function checks to see if the branch number is zero; if it is, then it sets it to the appropriate default value.

The main purpose of accessors is to encapsulate the access to fields to reduce the coupling within your code. Collections, such as arrays and vectors, being more complex than single value fields naturally need to have more than just the standard getter and setter member function implemented for them. In particular, because you can add and remove to and from collections, accessor member functions need to be included to do so. Add the following accessor member functions where appropriate for a field that is a collection:

Member Function type	Naming convention	Example
Getter for the collection	getCollection()	getOrderItems()
Setter for the collection	setCollection()	setOrderItems()
Insert an object into the collection	insertObject()	insertOrderItem()
Delete an object from the collection	deleteObject()	deleteOrderItem()
Create and add a new object into the collection	newObject()	newOrderItem()

The advantage of this approach is that the collection is fully encapsulated, allowing you to later replace it with another structure, perhaps a linked list or a B-tree.

4.4.3.4    Accessing several fields simultaneously

/** Set the position of the shape */

protected void setPosition(Float x, Float y)

{

	setXPosition(x);

	setYPosition(y);

}

/** Set the x position.  Important: Invoke setPosition(), not this member function. */

private void setXPosition(Float x)

{

	xPosition = x;

}

/** Set the y position of the shape

    Important: Invoke setPosition(), not this member function.

*/

private void setYPosition(Float y)

{

	yPosition = y;

}

4.5    Visibility of accessors

4.6    Always initialize static fields

5    Standards for Local Variables

5.1    Naming local variables

In general, local variables are named following the same conventions used for fields; in other words, use full English descriptors with the first letter of any non-initial word in uppercase.

For the sake of convenience, however, this naming convention is relaxed for several specific types of local variable:

• Streams
• Loop counters
• Exception objects

5.1.1    Naming streams

5.1.2    Naming loop counters

5.1.3    Naming exception objects

5.2    Declaring and documenting local variables

5.2.1    General comments about declaration

6    Standards For Parameters to Member Functions

6.1    Naming parameters

Parameters should be named following the same conventions used for local variables. As with local variables, name hiding is an issue.

Examples:

customer

inventoryItem

photonTorpedo

in

e

A viable alternative, taken from Smalltalk, is to use the naming conventions for local variables, with the addition of "a" or "an" on the front of the name. Adding "a" or "an" helps make the parameter stand out from local variables and fields, and avoids the name hiding problem. This is the preferred approach.

Examples:

aCustomer

anInventoryItem

aPhotonTorpedo

anInputStream

anException

6.2    Documenting parameters

Parameters to a member function are documented in the header documentation for the member function using the javadoc @param tag. You should describe the following:

1. What it should be used for. You need to document what a parameter is used for, so that other developers understand the full context of how the parameter will be used.
   
2. Any restrictions or preconditions. If the full range of values for a parameter is not acceptable to a member function, then the invoker of that member function needs to know. Perhaps a member function only accepts positive numbers or strings of less than five characters.
   
3. Examples. If it isn't completely obvious what a parameter should be, then you should provide one or more examples in the documentation.

6.2.1    Use interfaces for parameter types

Instead of specifying a class, such as Object, for the type of a parameter, if appropriate specify an interface, such as Runnable. The advantage is that this approach, depending on the situation, can be more specific (Runnable is more specific than Object), or potentially may be a better way to support polymorphism. Instead of insisting on a parameter being an instance of a class in a specific class hierarchy, specify that it supports a specific interface implying that it only needs to be polymorphically compliant to what you need.

7    Standards for Classes, Interfaces, Packages, and Compilation Units

7.1    Standards for classes

The standards that are important for classes are based on:

• naming conventions
• documentation conventions
• declaration conventions
• the public and protected interface

7.1.1    Naming classes

The standard Java convention uses a full English descriptor, starting with the first letter capitalized and using mixed case for the rest of the name. ([GOS96] and [AMB98])

Class names must be in the singular form.

Examples:

One of the fundamentals of object-oriented design is to minimize the public interface of a class. There are several reasons for this:

1. Ease of learning. To learn how to use a class, you should only have to understand its public interface. The smaller the public interface, the easier a class is to learn.
   
2. Reduced coupling. Whenever the instance of one class sends a message to an instance of another class, or directly to the class itself, the two classes become coupled. Minimizing the public interface implies that you are minimizing the opportunities for coupling.
   
3. Greater flexibility. This is directly related to coupling. Whenever you want to change the way that a member function in your public interface is implemented-perhaps you want to modify what the member function returns-then you potentially have to modify any code that invokes the member function. The smaller the public interface; the greater the encapsulation; and, therefore, the greater your flexibility.

It's clear that it's worth your while to minimize the public interface, but often what is not so clear is that you also want to minimize the protected interface as well. The basic idea is that, from the point of view of a subclass, the protected interfaces of all of its superclasses are effectively public. Any member function in the protected interface can be invoked by a subclass. Therefore, you want to minimize the protected interface of a class for the same reasons that you want to minimize the public interface.

7.1.4.1    Define the public interface first

Most experienced developers define the public interface of a class before they begin coding it. 

• First, if you don't know what services or behaviors a class will perform, then you still have some design work to do.
• Second, it enables you to stub out the class quickly so that other developers who rely on it can at least work with the stub until the "real" class has been developed. 
  
• Third, this approach provides you with an initial framework around which to build your class.

7.2    Standards for interfaces

The standards that are important for interfaces are based on:

• Naming conventions
• Documentation conventions

7.2.1    Naming interfaces

The Java convention is to name interfaces using mixed case, with the first letter of each word capitalized. The preferred Java convention for the name of an interface is to use a descriptive adjective, such as Runnable or Cloneable, although descriptive nouns, such as Singleton or DataInput, are also common [GOS96].

7.2.1.1    Alternative

With a few exceptions discussed below, you should always use full English descriptors when naming things. Furthermore, you should use lower case letters in general, but capitalize the first letter of class names and interface names, as well as the first letter of any non-initial word.

General Concepts:

• Use full English descriptors.
• Use terminology applicable to the domain.
• Use mixed case to make names readable.
• Use short forms sparingly, but if you do so then use them intelligently.
• Avoid long names (less than 15 characters is a good idea).
• Avoid names that are similar or differ only in case.
• Avoid underscores.

Item	Naming Convention	Example
Arguments/ parameters	Use a full English description of value/object being passed, possibly prefixing the name with "a" or "an". The important thing is to choose one approach and stick to it.	customer, account, - or - aCustomer, anAccount
Fields/ fields/ properties	Use a full English description of the field, with the first letter in lower case and the first letter of any non-initial word in uppercase.	firstName, lastName, warpSpeed
Boolean getter member functions	All boolean getters must be prefixed with the word "is". If you follow the naming standard for boolean fields described above then you simply give it the name of the field.	isPersistent(), isString(), isCharacter()
Classes	Use a full English description, with the first letters of all words capitalized.	Customer, SavingsAccount
Compilation unit files	Use the name of the class or interface, or if there is more than one class in the file than the primary class, ended with ".java" to indicate it's a source code file.	Customer.java, SavingsAccount.java, Singleton.java
Components/ widgets	Use a full English description that describes what the component is used for, with the type of the component concatenated onto the end.	okButton, customerList, fileMenu
Constructors	Use the name of the class.	Customer(), SavingsAccount()
Destructors	Java does not have destructors, but instead will invoke the finalize() member function before an object is garbage collected.	finalize()
Exceptions	It is generally accepted to use the letter "e" to represent exceptions.	e
Final static fields (constants)	Use all uppercase letters with the words separated by underscores. A better approach is to use final static getter member functions because they greatly increases flexibility.	MIN_BALANCE, DEFAULT_DATE
Getter member functions	Prefix the name of the field being accessed with "get".	getFirstName(), getLastName(), getWarpSpeeed()
Interfaces	Use a full English description describing the concept that the interface encapsulates, with the first letters of all words capitalized. It is customary to postfix the name with either "able", "ible", or "er" but this is not required.	Runnable, Contactable, Prompter, Singleton
Local variables	Use full English descriptions with the first letter in lowercase but do not hide existing fields/fields. For example, if you have a field named "firstName", do not have a local variable called "firstName".	grandTotal, customer, newAccount
Loop counters	It is generally accepted to use the letters i, j, or k, or the name counter.	i, j, k, counter
Packages	Use full English descriptions, using mixed case with the first letter of each word in uppercase, and everything else in lower case. For global packages, reverse the name of your Internet domain and concatenate the package name to this.	java.awt, com.ambysoft.www. persistence.mapping
Member Functions	Use a full English description of what the member function does, starting with an active verb whenever possible, with the first letter in lowercase.	openFile(), addAccount()
Setter member functions	Prefix the name of the field being accessed with "set".	setFirstName(), setLastName(), setWarpSpeed()

11.2    Java documentation conventions

11.2.1    Java comment types

The following chart describes the three types of Java comments and suggested uses for them.

Comment Type	Usage	Example
Documentation	Use documentation comments immediately before declarations of interfaces, classes, member functions, and fields to document them. Documentation comments are processed by javadoc, see below, to create external documentation for a class.	/** Customer: A customer is any person or organization that we sell services and products to. @author S.W. Ambler */
C style	Use C-style comments to document out lines of code that are no longer applicable, but that you want to keep just in case your users change their minds, or because you want to temporarily turn it off while debugging.	/* This code was commented out by B.Gustafsson, June 4 1999 because it was replaced by the preceding code. Delete it after two years if it is still not applicable. . . . (the source code ) */
Single line	Use single line comments internally within member functions to document business logic, sections of code, and declarations of temporary variables.	// Apply a 5% discount to all invoices // over $1000 as defined by the Sarek // generosity campaign started in // Feb. of 1995.

The following chart summarizes what to document regarding each portion of Java code that you write.

Item	What to Document
Arguments/ parameters	The type of the parameter What it should be used for Any restrictions or preconditions Examples
Fields/ fields/properties	Its description Document all applicable invariants Examples Concurrency issues Visibility decisions
Classes	The purpose of the class Known bugs The development and maintenance history of the class Document applicable invariants The concurrency strategy
Compilation units	Each class or interface defined in the class, including a brief description The file name and/or identifying information Copyright information
Getter member function	Document why lazy initialization was used, if applicable
Interfaces	The purpose How it should and should not be used
Local variables	Its use or purpose
Member Functions: Documentation	What and why the member function does what it does What a member function must be passed as parameters What a member function returns Known bugs Any exceptions that a member function throws Visibility decisions How a member function changes the object Include a history of any code changes Examples of how to invoke the member function if appropriate Applicable preconditions and postcondition
Member Functions: Internal comments	Control structures Why, as well as what, the code does Local variables Difficult or complex code The processing order
Package	The rationale for the package The classes in the package

11.3    Java coding conventions (general)

There are many conventions and standards which are critical to the maintainability and enhancability of your Java code. 99.9% of the time it is more important to program for people, your fellow developers, than it is to program for the machine. Making your code understandable to others is of utmost importance.

Convention Target	Convention
Accessor member functions	Consider using lazy initialization for fields in the database Use accessors for obtaining and modifying all fields Use accessors for "constants" For collections, add member functions to insert and remove items Whenever possible, make accessors protected, not public
Fields	Fields should always be declared private Do not directly access fields, instead use accessor member functions Do not use final static fields (constants), instead use accessor member functions Do not hide names Always initialize static fields
Classes	Minimize the public and protected interfaces Define the public interface for a class before you begin coding it Declare the fields and member functions of a class in the following order: constructors finalize() public member functions protected member functions private member functions private field
Local variables	Do not hide names Declare one local variable per line of code Document local variables with an inline comment Declare local variables immediately before their use Use local variables for one thing only
Member Functions	Document your code Paragraph your code Use whitespace, one line before control structures and two before member function declarations A member function should be understandable in less than thirty seconds Write short, single command lines Restrict the visibility of a member function as much as possible Specify the order of operations

12    References

Ref Code	Ref Information
[AMB98]	Ambler, S.W. (1998). Building Object Applications That Work: Your Step-By-Step Handbook for Developing Robust Systems with Object Technology. New York: SIGS Books/Cambridge University Press.
[COA97]	Coad, P. and Mayfield, M. (1997). Java Design: Building Better Apps & Applets. Upper Saddle River, NJ: Prentice Hall Inc.
[DES97]	DeSoto, A. (1997). Using the Beans Development Kit 1.0 February 1997: A Tutorial. Sun Microsystems.
[GOS96]	Gosling, J., Joy, B., Steele, G. (1996). The Java Language Specification. Reading, MA: Addison Wesley Longman Inc.
[GRA97]	Grand, M. (1997). Java Language Reference. Sebastopol, CA: O. Reilly & Associates, Inc.
[KAN97]	Kanerva, J. (1997). The Java FAQ. Reading, MA: Addison Wesley Longman Inc.
[KOE97]	Koenig, A. (1997). The Importance--and Hazards--of Performance Measurement. New York: SIGS Publications, Journal of Object-Oriented Programming, January, 1997, 9(8), pp. 58-60.
[LAF97]	Laffra, C. (1997). Advanced Java: Idioms, Pitfalls, Styles and Programming Tips. Upper Saddle River, NJ: Prentice Hall Inc.
[LEA97]	Lea, D. (1997). Concurrent Programming in Java: Design Principles and Patterns. Reading, MA: Addison Wesley Longman Inc.
[MCO93]	McConnell, S. (1993). Code Complete: A Practical Handbook of Software Construction. Redmond, WA: Microsoft Press.
[MEY88]	Meyer, B. (1988). Object-Oriented Software Construction. Upper Saddle River, NJ: Prentice Hall Inc.
[NAG95]	Nagler, J. (1995). Coding Style and Good Computing Practices. http://wizard.ucr.edu/~nagler/coding_style.html
[SUN96]	Sun Microsystems (1996). javadoc - The Java API Documentation Generator. Sun Microsystems.
[SUN97]	Sun Microsystems (1997). 100% Pure Java Cookbook for Java Developers: Rules and Hints for Maximizing the Portability of Java Programs. Sun Microsystems.
[VIS96]	Vision 2000 CCS Package and Application Team (1996). Coding Standards for C, C++, and Java. http://v2ma09.gsfc.nasa.gov/coding_standards.html

13    Glossary

100% pure: Effectively a "seal of approval" from Sun that says that a Java applet, application, or package, will run on ANY platform that supports the Java VM.

Accessor: A member function that either modifies or returns the value of a field. Also known as an access modifier. See Getter and Setter.

Analysis pattern: A modeling pattern that describes a solution to a business or domain problem.

Antipattern: An approach to solving a common problem, that in time proves to be wrong or highly ineffective.

Argument: See parameter.

BDK: Beans Development Kit

Block: A collection of zero or more statements enclosed in (curly) braces.

Braces: The characters { and }, known as an open brace and a close brace respectively, are used to define the beginning and end of a block.

Class: A definition, or template, from which objects are instantiated.

Class testing: The act of ensuring that a class and its instances (objects) perform as defined.

CMVC: Configuration Management and Version Control

Compilation unit: A source code file, either a physical one on disk or a "virtual" one stored in a database, in which classes and interfaces are declared.

Component: An interface widget such as a list, button, or window.

Constant getter: A getter member function that returns the value of a "constant," which may, in turn, be hard coded or calculated if necessary.

Constructor: A member function that performs any necessary initialization when an object is created.

Containment: An object contains other objects that it collaborates with to perform its behaviors. This can be accomplished either by the use of inner classes (JDK 1.1+) or the aggregation of instances of other classes within an object (JDK 1.0+).

CPU: Central processing unit

C-style comments: A Java comment format, /* & */, adopted from the C/C++ language that can be used to create multiple-line comments. Commonly used to "document out" unneeded or unwanted lines of code during testing.

Design pattern: A modeling pattern that describes a solution to a design problem.

Destructor: A C++ class member function that is used to remove an object from memory once it's no longer needed. Because Java manages its own memory, this kind of member function is not needed. Java does, however, support a member function that is similar in concept called finalize().

Documentation comments: A Java comment format, /** & */, that can be processed by javadoc to provide external documentation for a class file. The main documentation for interfaces, classes, member functions, and fields should be written with documentation comments.

Field: A variable, either a literal data type or another object, that describes a class or an instance of a class. Instance fields describe objects (instances) and static fields describe classes. Fields are also referred to as fields, field variables, and properties.

finalize(): A member function that is automatically invoked during garbage collection before an object is removed from memory. The purpose of this member function is to do any necessary cleanup, such as closing open files.

Garbage collection: The automatic management of memory, where objects that are no longer referenced are automatically removed from memory.

Getter: A type of accessor member function that returns the value of a field. A getter can be used to answer the value of a constant, which is often preferable to implementing the constant as a static field because this is a more flexible approach.

HTML: Hypertext markup language, an industry-standard format for creating Web pages.

Indenting: See paragraphing.

Inline comments: The use of a line comment to document a line of source code where the comment immediately follows the code, on the same line as the code. Single line comments are typically used for this, although C-style comments can also be employed.

Interface: The definition of a common signature, including both member functions and fields, which a class that implements an interface must support. Interfaces promote polymorphism by composition.

I/O: Input/output

Invariant: A set of assertions about an instance or class that must be true at all "stable" times, such as the periods before and after the invocation of a member function on the object or class.

Java: An industry-standard, object-oriented development language that is well-suited for developing applications for the Internet and applications that must operate on a wide variety of computing platforms.

javadoc: A utility included in the JDK that processes a Java source code file and produces an external document, in HTML format, describing the contents of the source code file based on the documentation comments in the code file.

JDK: Java Development Kit

Lazy initialization: A technique in which a field is initialized in its corresponding getter member function the first time it's needed. Lazy initialization is used when a field is not commonly needed and it either requires a large amount of memory to store or it needs to be read in from permanent storage.

Local variable: A variable defined within the scope of a block, often a member function. The scope of a local variable is the block in which it is defined.

Member function: A piece of executable code associated with a class or the instances of a class. Think of a member function as the object-oriented equivalent of a function.

Member function signature: See signature.

Method testing: The act of ensuring that a member function (member function) performs as defined.

Name hiding: This refers to the practice of using the same, or at least a similar, name for a field, variable, or argument as for one of higher scope. The most common abuse of name hiding is to name a local variable the same as an instance field. Name hiding should be avoided as it makes your code harder to understand and prone to bugs.

Overload: A member function is said to be overloaded when it's defined more than once in the same class (or in a subclass); the only difference being the signature of each definition.

Override: A member function is said to be overridden when it is redefined in a subclass and it has the same signature as the original definition.

Package: A collection of related classes.

Paragraphing: A technique where you indent the code within the scope of a code block by one unit, usually a horizontal tab, so as to distinguish it from the code outside of the code block. Paragraphing helps to increase the readability of your code.

Parameter: An argument passed to a member function, a parameter may be a defined type, such as a string, or an int, or an object.

postcondition: A property or assertion that will be true after a member function is finished running.

precondition: A constraint under which a member function will function properly.

Property: See field.

Setter: An accessor member function that sets the value of a field.

Signature: The combination of the type of parameters, if any, and their order that must be passed to a member function. This is also called the member function signature.

Single-line comments: A Java comment format, // , adopted from the C/C++ language that is commonly used for the internal member function documentation of business logic.

Tags: A convention for marking specified sections of documentation comments that will be processed by javadoc to produce professional-looking comments. Examples of tags include @see and @author.

Test harness: A collection of member functions for testing your code.

UML: Unified modeling language, which is an industry-standard modeling notation.

Visibility: A technique used to indicate the level of encapsulation of a class, member function, or field. The keywords-public, protected, and private-can be used to define visibility.

Whitespace: Blank lines, spaces, and tabs added to your code to increase its readability.

Widget: See component.

Rational Unified Process