java programming guidelines

7/31/2019 Java Programming Guidelines

1/58

Java Programming Guidelines

Document code: To Be Defined

Date: May 31, 2006


2/58

JAVA PROGRAMMING GUIDELINES

VERSION: 0.1

TCD

TABLE OF CONTENTS

1 INTRODUCTION............................................................................................................6

1.1 The first and last guideline.......................................................................................6

2 CODING STANDARDS ....................................................................................................7

2.1 Naming conventions ...............................................................................................7

2.2 Documentation conventions.....................................................................................8

2.2.1 Types of Java comments ......................................................................................9

2.2.2 A quick overview of javadoc................................................................................ 10

3 STANDARDS FOR MEMBER FUNCTIONS........................................................................12

3.1 Naming member functions..................................................................................... 12

3.1.1 Naming accessor member functions ..................................................................... 12

3.1.1.1 Getters...................................................................................................... 12

3.1.1.2 Setters...................................................................................................... 13

3.2 Naming constructors............................................................................................. 13

3.3 Member function visibility ...................................................................................... 13

3.4 Documenting member functions ............................................................................. 14

3.4.1 The member function header .............................................................................. 14

3.4.2 Internal documentation...................................................................................... 16

3.5 Techniques for writing clean code ........................................................................... 17

3.5.1 Document Your Code ......................................................................................... 18

3.5.2 Paragraph or indent your code ............................................................................ 18

3.5.3 Use whitespace in your code ............................................................................... 18

3.5.4 Follow the 30-second rule................................................................................... 18

3.5.5 Write short, single command lines........................................................................ 18

3.5.6 Specify the order of operations............................................................................ 19

4 STANDARDS FOR FIELDS AND PROPERTIES.................................................................20

4.1 Naming fields ...................................................................................................... 20


3/58


VERSION: 0.1

TCD

4.1.1 Naming components (widgets) ............................................................................ 20

4.1.1.1 Alternative for naming components: Hungarian notation.................................... 20

4.1.1.2 Alternative for naming components: postfix-Hungarian notation.......................... 21

4.1.1.3 Set component name standards..................................................................... 21

4.1.2 Naming constants ............................................................................................. 21

4.1.3 Naming collections ............................................................................................ 21

4.2 Field visibility ...................................................................................................... 22

4.2.1 Do not "hide" names.......................................................................................... 22

4.3 Documenting a field.............................................................................................. 22

4.4 Using accessor member functions ........................................................................... 23

4.4.1 Why use accessors?........................................................................................... 24

4.4.1.1 When not to use accessors ........................................................................... 24

4.4.2 Naming accessors ............................................................................................. 25

4.4.3 Advanced techniques for accessors ...................................................................... 25

4.4.3.1 Lazy initialization ........................................................................................ 25

4.4.3.2 Accessors for constants................................................................................ 26

4.4.3.3 Accessors for collections...............................................................................28

4.4.3.4 Accessing several fields simultaneously...........................................................29

4.5 Visibility of accessors............................................................................................ 29

4.6 Always initialize static fields................................................................................... 30

5 STANDARDS FOR LOCAL VARIABLES............................................................................31

5.1 Naming local variables .......................................................................................... 31

5.1.1 Naming streams ............................................................................................... 31

5.1.2 Naming loop counters ........................................................................................ 31

5.1.3 Naming exception objects................................................................................... 32

5.2 Declaring and documenting local variables................................................................ 32

5.2.1 General comments about declaration.................................................................... 32

6 STANDARDS FOR PARAMETERS TO MEMBER FUNCTIONS..............................................33

6.1 Naming parameters.............................................................................................. 33


4/58


VERSION: 0.1

TCD

6.2 Documenting parameters ...................................................................................... 33

6.2.1 Use interfaces for parameter types....................................................................... 34

7 STANDARDS FOR CLASSES, INTERFACES, PACKAGES, AND COMPILATION UNITS..........35

7.1 Standards for classes............................................................................................ 35

7.1.1 Naming classes................................................................................................. 35

7.1.2 Documenting a class.......................................................................................... 35

7.1.3 Class declarations ............................................................................................. 36

7.1.4 Minimize the public and protected interface ........................................................... 37

7.1.4.1 Define the public interface first...................................................................... 37

7.2 Standards for interfaces ........................................................................................ 38

7.2.1 Naming interfaces ............................................................................................. 38

7.2.1.1 Alternative................................................................................................. 38

7.2.2 Documenting interfaces...................................................................................... 38

7.3 Standards for packages......................................................................................... 39

7.3.1 Naming packages.............................................................................................. 39

7.3.2 Documenting packages ...................................................................................... 39

7.4 Standards for compilation units .............................................................................. 40

7.4.1 Naming compilation units ................................................................................... 40

7.4.2 Documenting compilation units............................................................................ 40

8 ERROR HANDLING AND EXCEPTIONS...........................................................................41

9 MISCELLANEOUS STANDARDS AND ISSUES .................................................................43

9.1 Reusing.............................................................................................................. 43

9.2 Importing classes................................................................................................. 43

9.3 Optimizing Java code............................................................................................ 43

9.4 Writing Java test harnesses ................................................................................... 44

10 PATTERNS OF SUCCESS...............................................................................................46

10.1 Using these standards effectively............................................................................ 46

10.2 Other factors that lead to writing successful code ...................................................... 46


5/58


VERSION: 0.1

TCD

11 SUMMARY................................................................................................................... 48

11.1 Java naming conventions....................................................................................... 48

11.2 Java documentation conventions ............................................................................ 50

11.2.1 Java comment types.......................................................................................... 50

11.2.2 What to document............................................................................................. 51

11.3 Java coding conventions (general) .......................................................................... 52

12 REFERENCES...............................................................................................................54

13 GLOSSARY..................................................................................................................55


6/58


VERSION: 0.1

TCD

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.


7/58


VERSION: 0.1

TCD

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.


8/58


VERSION: 0.1

TCD

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.


9/58


VERSION: 0.1

TCD

Example 1:

if ( grandTotal >= 1000.00)

{

grandTotal = grandTotal * 0.95;}

2.2.1 T YPES OFJAVA 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 anyperson or organization that wesell 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, 1999because it was replaced by thepreceding code. Delete it aftertwo years if it is still notapplicable.

. . . (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.

Table 2.1 - Summary of a suggested use for each type of comment

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


10/58


VERSION: 0.1

TCD

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 namedescription

Member Functions Describes the exceptions that a member functionthrows. 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.


11/58


VERSION: 0.1

TCD

@version text Classes, Interfaces Indicates the version information for a given piece of

code.

Table 2.2 - JDK javadoc documentation for further details

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.


12/58


VERSION: 0.1

TCD

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 N AMING 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 summarizedbelow.

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.


13/58


VERSION: 0.1

TCD

Alternative naming convention for Getters: has and can

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

Constructors are member functions that perform any necessary initialization when an object is first

created. Constructors are always given the same name as their class. For example, a constructor for

the class Customer would be Customer(). Note that the same case is used.

Examples:

Customer()

SavingsAccount()

PersistenceBroker()

This naming convention is set by Sun Microsystems and must be strictly adhered to.

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


14/58


VERSION: 0.1

TCD

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.


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.


needed by classes within the same package, but not

externally, and not by subclasses.

Table 3.1 Member function visibility

3.4 DOCUMENTING MEMBER FUNCTIONS

The manner in which you document a member function will often be the deciding factor as to whether

or not it is understandable and, therefore, maintainable and extensible.

3.4.1 T HE 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


15/58


VERSION: 0.1

TCD

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


16/58


VERSION: 0.1

TCD

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. Youwould 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 I NTERNAL DOCUMENTATION

In addition to the member function documentation, you also need to include comments within your

member functions to describe your work. The goal is to make your member function easier to

understand, maintain, and enhance.

There are two types of comments that you should use to document the internals of your code C-style

comments ( /* and */ ) and single-line comments ( // ). As previously discussed, you should seriously

consider choosing one style of comments for documenting the business logic of your code and one for

commenting out unneeded code. It is suggested that you use single-line comments for your business

logic, because you can use this style of comments both for full comment lines and for inline comments

that follow at the end of a line of code. Use C-style comments to document out lines of unneeded code

because it makes it easier to take out several lines with only one comment. Furthermore, because C-

style comments look so much like documentation comments, their use can be confusing, which takes

away from the understandability of your code. Therefore, use them sparingly.

Internally, you should always document the following:

1. Control structures. Describe each control structure, such as comparison statements and

loops. You should not have to read all the code in a control structure to determine what it

does; instead you should just have to look at a one or two line comment immediately

preceding it.

2. Why, as well as what, the code does. You can always look at a piece of code and figure out

what it does, but for code that is not obvious, you can rarely determine why it was done that

way. For example, you can look at a line of code and easily determine that a 5% discount is


17/58


VERSION: 0.1

TCD

being applied to the total of an order. That is easy. What is not easy is figuring out WHY that

discount is being applied. Obviously there is some sort of business rule that says to apply the

discount, so that business rule should at least be referred to in your code so that other

developers can understand why your code does what it does.

3. Local variables. Although we will discuss this in greater detail in Chapter 5, each local

variable defined in a member function should be declared on its own line of code and should

usually have an inline comment describing its use.

4. Difficult or complex code. If you find that you either can't rewrite it, or do not have the

time, then you must thoroughly document any complex code in a member function. A general

rule of thumb is that if your code is not obvious, then you need to document it

5. The processing order. If there are statements in your code that must be executed in a

defined order, then you should ensure that this fact gets documented [AMB98]. There's

nothing worse than making a simple modification to a piece of code only to find that it no

longer works, then spending hours looking for the problem only to find that you have gotten

things out of order.

6. Document your closing braces. Every so often, you will find that you have control

structures within control structures within control structures. Although you should avoid

writing code like this, sometimes you find that it is better to write it this way. The problem is

that it becomes confusing as to which ending brace the } character belongs to, which control

structure. The good news is that some code editors support a feature that, when you select a

open brace, will automatically highlight the corresponding closing one; the bad news is that

not every editor supports this. I have found that marking the ending braces with an inline

comment, such as //end if, //end for, //end switch, makes your code easier to

understand.

3.5 TECHNIQUES FOR WRITING CLEAN CODE

This section covers several techniques that help separate the professional developers from the hack

coders. These techniques are:

Document your code.

Paragraph or indent your code.

Use whitespace.

Follow the 30-second rule.

Write short, single command lines.

Specify the order of operations.


18/58


VERSION: 0.1

TCD

3.5.1 DOCUMENTYOUR CODE

Remember-if your code is not worth documenting, then it is not worth keeping.[NAG95] When you

apply the documentation standards and guidelines proposed in this document appropriately, you can

greatly enhance the quality of your code.

3.5.2 P ARAGRAPH OR INDENT YOUR CODE

One way to improve the readability of a member function is to paragraph it or, in other words, indent

your code within the scope of a code block. Any code within braces, the { and } characters, forms a

block. The basic idea is that the code within a block should be uniformly indented one unit.

The Java convention appears to be that the open brace is to be put on the line following the owner of

the block and that the closing brace should be indented one level. The important thing, pointed out by

[LAF97], is that your organization chooses an indentation style and sticks to it. Use the same

indentation style that your Java development environment uses for the code that it generates.

3.5.3 U SE 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 F OLLOW THE30-SECOND RULE

Other programmers should be able to look at your member function and fully understand what it does,

why it does it, and how it does it in less than 30 seconds. If this is not possible, then your code is too

difficult to maintain and should be improved. Thirty seconds; that's it. A good rule of thumb is that if a

member function is more than a screen, then it's probably too long.

3.5.5 W RITE SHORT, SINGLE COMMAND LINES

Your code should do one thing per line. Back in the days of punch cards, it made sense to try to get as

much functionality as possible on a single line of code. Whenever you attempt to do more than one

thing on a single line of code, you make it harder to understand. Why do this? We want to make our

code easier to understand so that it is easier to maintain and enhance. Just like a member function

should do one thing and one thing only, you should only do one thing on a single line of code.

Furthermore, you should write code that remains visible on the screen [VIS96]. You should not have

to scroll your editing window to the right to read the entire line of code, including code that uses inline

comments.


19/58


VERSION: 0.1

TCD

3.5.6 S PECIFY THE ORDER OF OPERATIONS

A really easy way to improve the understandability of your code is to use parentheses, also called

"round brackets", to specify the exact order of operations in your Java code [NAG95] and [AMB98]. If

you have to know the order of operations for a language to understand your source code, then

something is seriously wrong. This is mostly an issue for logical comparisons where you AND and OR

several other comparisons together. Note that if you use short, single-command lines, as previously

suggested, then this really should not become an issue.


20/58


VERSION: 0.1

TCD

4 STANDARDS FOR FIELDS AND PROPERTIES

The term field used here refers to a field that the BDK calls a property [DES97]. A field is a piece of

data that describes an object or class. Fields may be base data type, like a string or a float, or may be

an object, such as a customer or a bank account.

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:

firstName

zipCodeunitPrice

discountRate

orderItems

4.1.1 N AMING 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:

okButton

customerList

fileMenu

newFileMenuItem

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:

pbOk

lbCustomer

mFile

miNewFile


21/58


VERSION: 0.1

TCD

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 N AMING CONSTANTS

In Java, constants-values that do not change-are typically implemented as static final fields of classes.

The recognized convention is to use full English words, all in uppercase, with underscores between the

words [GOS96].

Examples:

MINIMUM_BALANCEMAX_VALUE

DEFAULT_START_DATE

The main advantage to this convention is that it helps you distinguish constants from variables. We

will see later in this document that you can greatly increase the flexibility and maintainability of your

code by not defining constants; instead you should define getter member functions that return the

value of constants.

4.1.3 N AMING COLLECTIONS

A collection, such as an array or a vector, should be given a pluralized name representing the types of

objects stored by the array. The name should be a full English descriptor, with the first letter of allnon-initial words capitalized.

Examples:

customers

orderItems

aliases

The main advantage of this convention is that it helps to distinguish fields that represent multiple

values (collections) from those that represent single values (non-collections).


22/58


VERSION: 0.1

TCD

4.2 FIELD VISIBILITY

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).

Table 4.1 Field visibility

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

Name hiding refers to the practice of naming a local variable, argument, or field the same (or similar)

as that of another one of greater scope. For example, if you have a field called firstName do not

create a local variable or parameter called firstName, or anything close to it like firstNames or

fistName. This makes your code difficult to understand and prone to bugs because other developers,

or you, will misread your code while they are modifying it and will make difficult-to-detect errors.

4.3 DOCUMENTING A FIELD

Every field should be documented well enough so that other developers can understand it. To be

effective, you need to document:

1. Its description. You need to describe a field so that people know how to use it.

2. All applicable invariants. Invariants of a field are the conditions that are always true about

it. For example, an invariant about the field dayOfMonth might be that its value is between 1

and 31 (obviously you could get far more complex with this invariant, restricting the value of

the field based on the month and the year). By documenting the restrictions on the value of a

field, you help to define important business rules that make it easier to understand how your

code works.


23/58


VERSION: 0.1

TCD

3. Examples. For fields that have complex business rules associated with them, you should

provide several example values to make them easier to understand. An example is often like a

good picture: it's worth a thousand words.

4. Concurrency issues. Concurrency is a new and complex concept for many developers;

actually, 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 them thoroughly.

5. Visibility decisions. If you have declared a field to be anything but private, then you should

document why you have done so. Field visibility was previously discussed in section 4.2, Field

visibility and the use of accessor member functions to support encapsulation is covered next

in section 4.4, Using of accessor member functions. The bottom line is that you better have

a really good reason for not declaring a variable as private.

4.4 USING ACCESSOR MEMBER FUNCTIONS

In addition to naming conventions, the maintainability of fields is achieved by the appropriate use of

accessor member functions-member functions that provide the functionality to either update a field or

to access its value. Accessor member functions come in two flavors: setters (also called mutators) and

getters. A setter modifies the value of a variable, whereas a getter obtains it for you.

Although accessor member functions used to add overhead to your code, Java compilers are now

optimized for their use so this is no longer true. Accessors help to hide the implementation details of

your class. By having two control points at most from which a variable is accessed, one setter and one

getter, you are able to increase the maintainability of your classes by minimizing the points at which

changes need to be made. Optimization of Java code is discussed in section 9.3, Optimizing Java

Code.

One of the most important standards that your organization can enforce is the use of

accessors. Some developers do not want to use accessor member functions because they do not

want to type the few extra keystrokes required; for example, for a getter you need to type in "get"

and "()" above and beyond the name of the field. The bottom line is that the increased maintainability

and extensibility from using accessors more than justifies their use.

Accessors are the only place to access fields. A key concept with the appropriate use of accessor

member functions is that the ONLY member functions that are allowed to directly work with a field arethe accessor member functions themselves. Yes, it's possible to directly access a private field within

the member functions of the class in which the field is defined, but you do not want to do so because

you would increase the coupling within your class.


24/58


VERSION: 0.1

TCD

4.4.1 W HY USE ACCESSORS?

"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 theconstant/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.


25/58


VERSION: 0.1

TCD

4.4.2 N AMING ACCESSORS

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

firstName string getFirstName()

address Address object getAddress()

persistent boolean isPersistent()

customerNo int getCustomerNo()

orderItems Array of OrderItem objects getOrderItems()

Table 4.2 Naming accessors

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.


26/58


VERSION: 0.1

TCD

/**Answers the branch number, which is the leftmost

* four digits of the full account number.

* Account numbers are in the format BBBBAAAAAA.

*/

protected int getBranchNumber(){

if (branchNumber == 0)

{

// The default branch number is 1000, which

// is the main branch in downtown Bedrock.

setBranchNumber(1000);

}

return branchNumber;

}

It is quite common to use lazy initialization for fields that are actually other objects stored in the

database. For example, when you create a new inventory item, you do not need to fetch whatever

inventory item type from the database that you have set as a default. Instead, use lazy initialization to

set this value the first time it is accessed, so that you only have to read the inventory item type object

from the database when and if you need it.

This approach is advantageous for objects that have fields that are not regularly accessed. Why incur

the overhead of retrieving something from persistent storage if you are not going to use it?

Whenever lazy initialization is used in a getter member function, you should document why the default

value is what it is, as we saw in the example above. When you do this, you take the mystery out of

how fields are used in your code, which improves both its maintainability and its extensibility.

4.4.3.2 Accessors for constants

The common Java idiom is to implement constant values as static final fields. This approach makes

sense for "constants" that are guaranteed to be stable. For example, the class Boolean implements

two static final fields called TRUE and FALSE, which represents the two instances of that class. It

would also make sense for a DAYS_IN_A_WEEK constant whose value probably is never going to

change.

However, many so-called business "constants" change over time because the business rules change.

Consider the following example: The Archon Bank of Cardassia (ABC) has always insisted that an

account has a minimum balance of $500 if it is to earn interest. To implement this, we could add a

static field named MINIMUM_BALANCE to the class Account that would be used in the member

functions that calculate interest. Although this would work, it is not flexible. What happens if the

business rules change and different kinds of accounts have different minimum balances, perhaps $500

for savings accounts but only $200 for checking accounts? What would happen if the business rules

were to change to a $500 minimum balance in the first year, $400 in the second, $300 in the third,

and so on? Perhaps the rule will be changed to $500 in the summer, but to only $250 in the winter?

Perhaps a combination of all of these rules will need to be implemented in the future.


27/58


VERSION: 0.1

TCD

The point being made is that implementing constants as fields is not flexible. A much better solution is

to implement constants as getter member functions. In our example above, a static (class) member

function called getMinimumBalance() is far more flexible than a static field called

MINIMUM_BALANCE because we can implement the various business rules in this member function

and subclass it appropriately for various kinds of accounts.

/** Get the value of the account number. Account numbers are in the following

* format: BBBBAAAAAA, where BBBB is the branch number and

* AAAAAA is the branch account number.

*/

public long getAccountNumber()

{

return ( ( getBranchNumber() * 100000 ) + getBranchAccountNumber() );

}

/** Set the account number. Account numbers are in the following

* format: BBBBAAAAAA where BBBB is the branch number and

* AAAAAA is the branch account number.

*/

public void setAccountNumber(int newNumber)

{

setBranchAccountNumber( newNumber % 1000000 );

setBranchNumber( newNumber / 1000000 );

}

Another advantage of constant getters is that they help to increase the consistency of your code.

Consider the code shown above-it doesn't work properly. An account number is the concatenation of

the branch number and the branch account number. Testing our code, we find that the setter member

function, setAccountNumber() does not update branch account numbers properly; it takes the three

leftmost digits, not four. That is because we used 1,000,000 instead of 100,000 to extract the field

branchAccountNumber. Had we used a single source for this value, the constant getter

getAccountNumberDivisor() as we see below, our code would have been more consistent and

would have worked.

/**

*Returns the divisor needed to separate the branch account number from the

*branch number within the full account number.

*Full account numbers are in the format BBBBAAAAAA.

*/public int getAccountNumberDivisor()

{

return ( (long) 1000000);

}

/**

*Get the value of the account number. Account numbers are in the following

*format: BBBBAAAAAA, where BBBB is the branch number and


28/58


VERSION: 0.1

TCD

*AAAAAA is the branch account number.

*/

public long getAccountNumber()

{

return ( ( getBranchNumber() * getAccountNumberDivisor() ) +getBranchAccountNumber() );

}

/**

*Set the account number. Account numbers are in the following

*format: BBBBAAAAAA where BBBB is the branch number and

*AAAAAA is the branch account number.

*/

public void setAccountNumber(int newNumber)

{

setBranchAccountNumber( newNumber % getAccountNumberDivisor() );

setBranchNumber( newNumber / getAccountNumberDivisor() );}

By using accessors for constants, we decrease the chance of bugs and, at the same time, increase the

maintainability of our system. When the layout of an account number changes, and we know that it

eventually will, chances are that our code will be easier to change because we have both hidden and

centralized the information needed to build or divide account numbers.

4.4.3.3 Accessors for collections

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

Table 4.3 Accessors for collections

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.


29/58


VERSION: 0.1

TCD

4.4.3.4 Accessing several fields simultaneously

One of the strengths of accessor member functions is that they enable you to enforce business rules

effectively. Consider, for example, a class hierarchy of shapes. Each subclass ofShape knows its

position via the use of two fields "xPosition and yPosition" and can be moved on the screen on a

two-dimensional plane by invoking the member function move(Float xMovement, Float

yMovement). For our purposes, it does not make sense to move a shape along one axis at a time;

instead we'll move along both the x and the y axes simultaneously (it is acceptable to pass a value of

0.0 as for either parameter of the move() member function). The implication is that the move()

member function should be public, but the member functions setXPosition() and setYPosition()

should both be private, being invoked by the move() member function appropriately.

An alternative implementation would be to introduce a setter member function that updates both

fields at once, as shown below. The member functions setXPosition() and setYPosition() would still

be private so that they may not be invoked directly by external classes or subclasses (you would wantto add some documentation, shown below, indicating that they should not be directly invoked).

/** 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

Always strive to make accessors protected, so that only subclasses can access the fields. Only when

an "outside class" needs to access a field should you make the corresponding getter or setter public.

Note that it's common that the getter member function be public and the setter protected.

Sometimes you need to make setters private to ensure certain invariants hold. For example, an Order

class may have a field representing a collection of OrderItem instances, and a second field called

orderTotal, which is the total of the entire order. The orderTotal is a convenience field that is the

sum or all subtotals of the ordered items. The only member functions that should update the value of


30/58


VERSION: 0.1

TCD

orderTotal are those that manipulate the collection of order items. Assuming that those member

functions are all implemented in Order, you should make setOrderTotal() private, even though

getOrderTotal() is more than likely public.

4.6 ALWAYS INITIALIZE STATIC FIELDS

Static fields, also known as class fields, should be given valid values because you cannot assume that

instances of a class will be created before a static field is accessed.


31/58


VERSION: 0.1

TCD

5 STANDARDS FOR LOCAL VARIABLES

A local variable is an object or data item that is 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. The important coding

standards for local variables focus on:

Naming conventions

Declarations and documentation conventions

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 N AMING STREAMS

When there is a single input and/or output stream being opened, used, and then closed within a

member function, the common convention is to use In and Out for the names of these streams,

respectively [GOS96]. For a stream used for both input and output, the implication is to use the name

inOut.

A common alternative to this naming convention, although conflicting with Sun's recommendations, is

to use the names inputStream, outputStream, and ioStream instead of In, Out, and inOut

respectively.

5.1.2 N AMING LOOP COUNTERS

Because loop counters are a very common use for local variables, and because it was acceptable in

C/C++, in Java programming the use ofi,j, or k, is acceptable for loop counters [GOS96]. If you use

these names for loop counters, use them consistently.

A common alternative is to use names like loopCounter or simply counter, but the problem with this

approach is that you often find names like counter1 and counter2 in member functions that require

more than one counter. The bottom line is that i,j, k work as counters; they're quick to type in and

they're generally accepted.


32/58


VERSION: 0.1

TCD

5.1.3 N AMING EXCEPTION OBJECTS

Because exception handling is also very common in Java coding, the use of the letter e for a generic

exception is considered acceptable [GOS96].

5.2 DECLARING AND DOCUMENTING LOCAL VARIABLES

There are several conventions regarding the declaration and documentation of local variables in Java.

These conventions are:

Declare one local variable per line of code. This is consistent with one statement per line

of code and makes it possible to document each variable with an inline comment.

Document local variables with an inline comment. Inline commenting is a style, where a

single line comment, denoted by //, immediately follows a command on the same line of code

(this is called an endline comment). You should document what a local variable is used for,where its use is appropriate, and why it is used. This makes your code easier to understand.

Use local variables for one thing only. Whenever you use a local variable for more than

one reason, you effectively decrease its cohesion and make it difficult to understand. You also

increase the chances of introducing bugs into your code from the unexpected side effects of

previous values of a local variable from earlier in the code. Yes, reusing local variables is more

efficient because less memory needs to be allocated, but reusing local variables decreases the

maintainability of your code and makes it more fragile. This usually is not worth the small

savings gained from not having to allocate more memory.

5.2.1 G ENERAL COMMENTS ABOUT DECLARATION

Local variables that are declared between lines of code, for example, within the scope of an if

statement, can be difficult to find by people who are not familiar with your code.

One alternative to declaring local variables immediately before their first use is to instead declare

them at the top of the code. Because your member functions should be short anyway, see section

3.5.5, Write short, single command lines, it should not be all that bad having to go to the top of your

code to determine what the local variable is all about.


33/58


VERSION: 0.1

TCD

6 STANDARDS FOR PARAMETERS TO MEMBERFUNCTIONS

The standards that are important for parameters and arguments to member functions focus on how

they are named and how they are documented. The term parameter is used to refer to a member

function argument.

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

inventoryItemphotonTorpedo

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

aPhotonTorpedoanInputStream

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.


34/58


VERSION: 0.1

TCD

6.2.1 U SE 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.


35/58


VERSION: 0.1

TCD

7 STANDARDS FOR CLASSES, INTERFACES, PACKAGES,AND COMPILATION UNITS

This chapter concentrates on standards and guidelines for classes, interfaces, packages, and

compilation units. A class is a template from which objects are instantiated (created). Classes contain

the declaration of fields and member functions. Interfaces are the definition of a common signature,

including both member functions and fields, which a class that implements an interface must support.

A package is a collection of related classes. Finally, a compilation unit is a source code file in which

classes and interfaces are declared. Because Java allows compilation units to be stored in a database,

an individual compilation unit may not directly relate to a physical source code file.

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 N AMING 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:

Customer

Employee

Order

OrderItem

FileStream

String

7.1.2 DOCUMENTING A CLASS

The following information should appear in the documentation comments immediately preceding the

definition of a class:

1. The purpose of the class. Developers need to know the general purpose of a class so they

can determine whether or not it meets their needs. Make it a habit to document any good

things to know about a class; for example, is it part of a pattern or are there any interesting

limitations to using it [AMB98]?


36/58


VERSION: 0.1

TCD

2. Known bugs. If there are any outstanding problems with a class, they should be documented

so that other developers understand the weaknesses and difficulties with the class.

Furthermore, the reason for not fixing the bug also needs to be documented. Note that if a

bug is specific to a single member function, then it should be directly associated with themember function instead.

3. The development or maintenance history of the class. It's common practice to include a

history table listing dates, authors, and summaries of changes made to a class. This provides

maintenance programmers insight into any modifications made to a class in the past and

documents who has done what to a class.

4. Document applicable invariants. An invariant is a set of assertions about an instance or

class that must be true at all "stable" times, where a stable time is defined as the period

before a member function is invoked on the object or class and immediately after a member

function is invoked [MEY88]. By documenting the invariants of a class, you provide valuableinsight to other developers about how a class can be used.

5. The concurrency strategy. Any class that implements the interface Runnable should have

its concurrency strategy fully described. Concurrent programming is a complex topic that's

new for many programmers; therefore you need to invest the extra time to ensure that people

can understand your work. It's important to document your concurrency strategy and why you

chose that strategy over others. Common concurrency strategies [LEA97] include the

following:

synchronized objects

balking objects

guarded objects

versioned objects

concurrency policy controllers

acceptors

7.1.3 C LASS DECLARATIONS

One way to make your classes easier to understand is to declare them in a consistent manner. The

common approach in Java is to declare a class in the following order:

public member functions

public fields

protected member functions

protected fields

private member functions


37/58


VERSION: 0.1

TCD

private fields

[LAF97] points out constructors and finalize() should be listed first, presumably because these are

the first member functions that another developer will look at to understand how to use the class.

Furthermore, because we have a standard to declare all fields as private, the declaration order really

comes down to:

constructors

finalize()

public member functions

protected member functions

private member functions

private fields

Within each grouping of member functions, it's common to list them in alphabetical order. Many

developers choose to list the static member functions within each grouping first, followed by instance

member functions; and then within each of these two sub-groupings, list the member functions

alphabetically. Both of these approaches are valid; you just need to choose one and stick to it.

7.1.4 M INIMIZE THE PUBLIC AND PROTECTED INTERFACE

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 thepublic 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 super-classes 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.


38/58


VERSION: 0.1

TCD

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 N AMING 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

Prefix the letter "I" to the interface name. As [COA97] suggests, appending the letter "I" to the

front of an interface names results in names like ISingleton or IRunnable. This approach helps to

distinguish interface names from class and package names. I like this potential naming convention for

the simple fact that it makes your class diagrams, sometimes referred to as object models, easier to

read. The main disadvantage is that the existing interfaces, such as Runnable, are not named using

this approach. This interface naming convention is also popular for Microsoft's COM/DCOM

architecture.

7.2.2 DOCUMENTING INTERFACES

The following information should appear in the documentation comments immediately preceding the

definition of an interface:

1. State the purpose. Before other developers will use an interface, they need to understandthe concept that it encapsulates. In other words, they need to know its purpose. A really good

test of whether or not you need to define an interface is whether or not you can easily

describe its purpose. If you have difficulties describing it, then chances are pretty good you

don't need the interface to begin with. Because the concept of interfaces is new to Java,

people are not yet experienced in their appropriate use and they're likely to overuse them

because they are new.


39/58


VERSION: 0.1

TCD

2. How interfaces should and should not be used. Developers need to know both how an

interface is to be used, as well as how it should not be used [COA97].

Because the signature for member functions is defined in an interface, for each member function

signature you need to fol

java programming guidelines

Documents