|
University of Oxford |
Computing Services |
|
Java: steps towards good quality code |
|
| Author: Barry Cornelius Date: 14th May 2001 |
Good practice is best acquired from the start. Beginners find it difficult to learn one thing one day only to be told later that it is best done in some other way. This document describes some of the ideas I teach when introducing interfaces and classes to students. My aim is to get beginners to produce good quality code for interfaces and classes from the outset.
final Date tTodaysDate = new Date(2000, 12, 25); final Date tNoelDate = new Date(2000, 12, 25); final boolean tIsChristmasDay = tTodaysDate.equals(tNoelDate);
public boolean equals(final Date pDate)
{
return iYear==pDate.iYear && iMonth==pDate.iMonth && iDay==pDate.iDay;
}
| Hashtable | contains, containsKey, get, put, remove |
| Vector | contains, indexOf |
| List | contains, indexOf, remove |
| Map | containsKey, containsValue, get, put, remove |
| Set | add, contains, remove |
public boolean equals(final Object pObject)
{
if ( pObject==null || getClass()!=pObject.getClass() )
{
return false;
}
final Date tDate = (Date)pObject;
return iYear==tDate.iYear && iMonth==tDate.iMonth && iDay==tDate.iDay;
}
Since the equals method appears in a class called Date, you would think that the target of equals must be an object of class Date, and so this kind of call of getClass always returns a value describing the class Date. However, suppose we derive a class called NamedDate from Date:
public class NamedDate extends Date
{
private String iName:
...
}
Suppose that NamedDate does not override equals. If we write:
tFirstNamedDate.equals(tSecondNamedDate)then this will be a call of Date's equals method and both calls of getClass will return values describing the class NamedDate. So, even though this code appears in the class declaration for Date, in some circumstances the first call of getClass will return a value describing a subclass of the class Date.
public boolean equals(final Object pObject)
{
if ( ! (pObject instanceof Date) )
{
return false;
}
final Date tDate = (Date)pObject;
return iYear==tDate.iYear && iMonth==tDate.iMonth && iDay==tDate.iDay;
}
public int hashCode(); public boolean equals(Object pObject);
| Hashtable | contains, containsKey, get, put, remove |
| HashMap | containsKey, containsValue, get, put, remove |
| HashSet | add, contains, remove |
Here is the contract that hashCode needs to satisfy:
public int hashCode()
{
return 0;
}
public int hashCode()
{
return iMonth;
}
final Date tNoelDate = new Date(2000, 12, 25); final int tValue = tNoelDate.hashCode();will assign the value 12 to tValue.
For example, suppose we want to store the dates when various composers died:
| Bach | 1750-08-28 |
| Beethoven | 1827-03-26 |
| Cage | 1992-08-12 |
| Chopin | 1849-10-17 |
| Copland | 1990-12-02 |
| Elgar | 1934-02-23 |
| Handel | 1759-04-14 |
| Mendelssohn | 1847-11-04 |
| Purcell | 1695-11-21 |
| Sibelius | 1957-09-20 |
| Stanford | 1924-03-29 |
| Tallis | 1585-11-23 |
| Tchaikovsky | 1893-11-06 |
| Vaughan-Williams | 1958-08-26 |
| Walton | 1983-03-08 |
Suppose we add each of these dates to a HashSet, e.g. for Bach:
Date tDeathOfBach = new Date(1750, 8, 28); tHashSet.add(tDeathOfBach);
HashSet's add method uses Date's hashCode function, and so the values will be stored in 12 buckets:
Then, when later we ask the collection object whether it has the value 1893-11-06 (the date when Tchaikovsky died), the contains method can call hashCode on this value and, because this produces the value 11, the contains method only checks the values in the 11th bucket. The code of the contains method uses equals on each of these values in turn returning the value true if and only if it finds the value (in this case, the value 1893-11-06).
public int hashCode()
{
return 0;
}
| the code of the hashCode method | time taken |
| return 0; | 14826 |
| return iMonth; | 1235 |
| return iYear*10000 + iMonth*100 + iDay; | 36 |
public interface Comparable
{
public int compareTo(Object pObject);
}
public class Date implements Comparable
{
...
public int compareTo(final Object pObject)
{
final Date tDate = (Date)pObject;
int tResult = iYear - tDate.iYear;
if (tResult==0)
{
tResult = iMonth - tDate.iMonth;
if (tResult==0)
{
tResult = iDay - tDate.iDay;
}
}
return tResult;
}
}
final Set tOccurrences = new TreeSet(): tOccurrences.add(tDeathOfBach);
If a class such as Date fails to implement the Comparable interface, or its implementation of compareTo provides inappropriate code, a client class can still store Date objects in a TreeSet or a TreeMap provided it creates the TreeSet/TreeMap using a constructor that is passed an object that implements the Comparator interface ([18]). This interface requires the object to provide the method:
public int compare(Object pObject1, Object pObject2);This method returns a negative integer, zero, or a positive integer depending on whether the value of pObject1 is less than, equal to, or greater than that of pObject2.
Here is an example. Suppose, bizarrely, we chose to compare dates only on the year field. We could provide:
public class MyDateComparator implements java.util.Comparator
{
public int compare(final Object pObject1, final Object pObject2)
{
return ((Date)pObject1).getYear() - ((Date)pObject2).getYear();
}
}
and then use:
final MyDateComparator tMyDateComparator = new MyDateComparator(); final Set tOccurrences = new TreeSet(tMyDateComparator): tOccurrences.add(tDeathOfBach);
Date tBirthDate = new Date(2000, 1, 24);
Person tSomePerson = new Person("Joe", tBirthDate);
where Person is as follows:
public class Person
{
private String iName;
private Date iDateOfBirth;
public Person(final String pName, final Date pDateOfBirth)
{
iName = pName;
iDateOfBirth = pDateOfBirth; // share
...
iDateOfBirth = (Date)pDateOfBirth.clone(); // clone
iDateOfBirth = new Date(pDateOfBirth); // clone
public Object clone();
public class Date
{
...
public Object clone()
{
return super.clone();
}
}
public class Date implements Cloneable
{
...
public Object clone()
{
try
{
return super.clone();
}
catch(final CloneNotSupportedException pCloneNotSupportedException)
{
throw new InternalError();
}
}
}
Object's clone method only produces a shallow copy. So, if a class has one or more fields that are of a reference type, we may want to provide a deep copy by cloning these fields. For example, for the Person class, we could provide:
public class Person implements Cloneable
{
...
public Object clone()
{
try
{
final Person tPerson = (Person)super.clone();
if (iDateOfBirth!=null)
{
tPerson.iDateOfBirth = (Date)iDateOfBirth.clone();
}
return tPerson;
}
catch(final CloneNotSupportedException pCloneNotSupportedException)
{
throw new InternalError();
}
}
}
Perhaps a Java programmer's first use of an interface occurs with handling the events of a GUI. For example, suppose a window (JFrame) has a button (JButton):
final JFrame tJFrame = new JFrame("some title");
final JButton tJButton = new JButton("click here");
final Container tContentPane = tJFrame.getContentPane();
tContentPane.add(tJButton, BorderLayout.CENTER);
tJFrame.pack():
tJFrame.setVisible(true);
If the program has to react to a click of the button, the program has to create an object and register it as a listener:
final JButtonListener tJButtonListener = new JButtonListener(); tJButton.addActionListener(tJButtonListener);
Here we have created an object of a class called JButtonListener and passed tJButtonListener as the argument of the addActionListener method. The documentation of addActionListener states that its parameter is of the interface type ActionListener. So JButtonListener must be a class that implements the ActionListener interface:
public class JButtonListener implements ActionListener
{
...
}
Looking again at the documentation of the ActionListener interface, you will see that this interface is simply:
public interface ActionListener
{
public void actionPerformed(ActionEvent pActionEvent);
}
So this means that JButtonListener could be something like:
public class JButtonListener implements ActionListener
{
public void actionPerformed(final ActionEvent pActionEvent)
{
final Date tDate = new Date();
System.out.println(tDate);
}
}
Java's Collections API provides classes that can be used for representing collections of objects, such as lists, sets and maps. It provides two classes for each of these. For lists, it provides classes called ArrayList and LinkedList; for sets, it provides classes called HashSet and TreeSet; and, for maps, it provides classes called HashMap and TreeMap. Often your choice of the class will be determined by the particular operations that you want to perform: one of the classes performs faster than the other.
Suppose we want to represent a list of objects.
If we are using the Collections API,
we have a choice between using
an
ArrayList
and a
LinkedList:
The
ArrayList
class performs well in most situations.
However, the
LinkedList
class performs better than
ArrayList
when the operations that dominate
involve adding or removing items at the
ends of the list.
Having made a choice over the class, then the operations that you can perform on the list are the same. So, if tList points to an ArrayList object or a LinkedList object, we can perform operations such as:
tList.add("Tom");
tList.add("Harry");
tList.add(1, "Dick");
tList.remove(1);
tList.set(1, "Dick");
String tString = (String)tList.get(1);
Before executing this code, we need to create the list object. The code we use for this depends on whether we want an ArrayList or a LinkedList. So we can choose between:
ArrayList tList = new ArrayList();
LinkedList tList = new LinkedList();
However, the above is not regarded as good programming style.
Sun's documentation for the Collections API
encourages you to code in terms of interfaces called
List,
Set
and
Map
instead of writing code in terms of specific classes
(such as
ArrayList
and
LinkedList).
So use either:
List tList = new ArrayList();
List tList = new LinkedList();
Instead of using a variable tList which is of a specific class type (ArrayList or LinkedList), we are now using a variable tList which is of the interface type List. A variable that is of an interface type may point to any object that is of a class that implements that interface.
If a list object has to be passed as an argument to a method, then this style of programming recommends that the parameter be of the interface type rather than of the specific class type. So, instead of the method having a header like:
public void processList(ArrayList pArrayList);
public void processList(List pList);
With this style of programming, most of the code is written in terms of the List interface. The only place where either ArrayList or LinkedList has to be mentioned is when we create the list object, i.e., the commitment to use an ArrayList instead of a LinkedList (or vice-versa) only appears where the object is created.
So far, the examples have involved interfaces that others have provided. So, when might we want to provide our own interface declarations?
We may want to do this if we have many classes that provide the same set of operations and we want to execute code that processes various objects of these different classes.
Suppose we are processing geometrical figures, some of which are circles and others are rectangles. Suppose we want to find out the area or the perimeter of these figures. We could provide the interface:
public interface Figure
{
public double area();
public double perimeter();
}
and provide classes called Circle and Rectangle. Here is some code for Circle:
public class Circle implements Figure
{
private double iRadius;
public Circle(final double pRadius)
{
iRadius = pRadius;
}
public double area()
{
return Math.PI*iRadius*iRadius;
}
public double perimeter()
{
return 2.0*Math.PI*iRadius;
}
...
}
The code for Rectangle is similar.
Suppose we store several objects of these two classes in a list:
final List tList = new ArrayList(); tList.add( new Circle(100.0) ); tList.add( new Rectangle(200.0, 300.0) ); ...
We can then process the elements of the list using code like:
final Iterator tIterator = tList.iterator();
while ( tIterator.hasNext() )
{
final Figure tFigure = (Figure)tIterator.next();
System.out.println( tFigure.area() );
}
By coding the classes as implementations of an interface we can perform operations on objects that are of different classes.
When I came to examine Java for the first time, it was from a background in many programming languages including Modula-2, Ada 83 and C++.
In Modula-2, ‘a separate module is split into two parts: a definition part and an implementation part. The definition module gives information as to what services are provided; and the implementation module contains the full code of the module: it specifies how the services are to be provided. These two parts of a separate module are stored in two different files’ ([3]). By using an opaque type, clients can be written that are not dependent on the code of the implementation module.
In a similar way, in Ada 83, a package can be split into two parts: a package specification and a package body. A limited private type can be used in much the same way as an opaque type can be used in Modula-2.
Both Modula-2 and Ada 83 provide different constructs for the interface and the implementation. This is not so with C++ where, if you wish to use this style of programming, the class construct is used for both.
In his fascinating book 'The Design and Evolution of C++' ([16]), Stroustrup (the designer of C++) says: ‘I ... made matters worse for the C++ community by not properly explaining the use of derived classes to achieve the separation of interface and implementation. I tried (see for example Section 7.6.2 of [15]), but somehow I never got the message across. I think the reason for this failure was primarily that it never occurred to me that many (most?) C++ programmers and non C++ programmers looking at C++ thought that because you could put the representation right in the class declaration that specified the interface, you had to.’
To make it easier to express this separation, Stroustrup added the concept of an abstract class to C++. ‘The very last feature added to Release 2.0 before it shipped [in June 1989] was abstract classes. Late modifications to releases are never popular, and late changes to the definition of what will be shipped are even less so. My impression was that several members of management thought I had lost touch with the real world when I insisted on this feature.’
‘An abstract class represents an interface. Direct support for abstract classes
In C++, an abstract class is a class that has one or more pure virtual functions:
class figure
{
public:
virtual double area() = 0;
virtual double perimeter() = 0;
};
In Modula-2 and Ada 83, it is easy to separate the interface from the implementation. So having this background, and having taught Modula-2 in this way for many years ([3]), when I started to look at Java I wondered whether the same style of programming could be achieved (and should be adopted) in Java.
If we need to represent some objects in a Java program, at the same time as producing a class declaration that describes the implementation, we could also produce an interface declaration that describes the operations provided by the methods of the class.
An interface declaration for dates could be:
public interface Date
{
public int getYear();
public int getMonth();
public int getDay();
public void setYear(int pYear);
public void setMonth(int pMonth);
public void setDay(int pDay);
public boolean equals(Object pObject);
public int hashCode();
public String toString();
}
And a class declaration for dates could be:
import java.util.StringTokenizer;
public class DateImpl implements Date
{
private int iYear;
private int iMonth;
private int iDay;
public DateImpl()
{
this(1970, 1, 1);
}
public DateImpl(final Date pDate)
{
final DateImpl tDateImpl = (DateImpl)pDate;
iYear = tDateImpl.iYear;
iMonth = tDateImpl.iMonth;
iDay = tDateImpl.iDay;
}
public DateImpl(final int pYear, final int pMonth, final int pDay)
{
iYear = pYear;
iMonth = pMonth;
iDay = pDay;
}
public DateImpl(final String pDateString)
{
try
{
final StringTokenizer tTokens =
new StringTokenizer(pDateString, "-");
final String tYearString = tTokens.nextToken();
iYear = Integer.parseInt(tYearString);
final String tMonthString = tTokens.nextToken();
iMonth = Integer.parseInt(tMonthString);
final String tDayString = tTokens.nextToken();
iDay = Integer.parseInt(tDayString);
}
catch(final Exception pException)
{
iYear = 1970;
iMonth = 1;
iDay = 1;
throw new IllegalArgumentException();
}
}
public int getYear() { return iYear; }
public int getMonth() { return iMonth; }
public int getDay() { return iDay; }
public void setYear(final int pYear) { iYear = pYear; }
public void setMonth(final int pMonth) { iMonth = pMonth; }
public void setDay(final int pDay) { iDay = pDay; }
public boolean equals(final Object pObject)
{
if ( pObject==null || getClass()!=pObject.getClass() )
{
return false;
}
final DateImpl tDateImpl = (DateImpl)pObject;
return iYear==tDateImpl.iYear &&
iMonth==tDateImpl.iMonth && iDay==tDateImpl.iDay;
}
public int hashCode()
{
return 0;
}
public String toString()
{
return iYear + "-" + iMonth/10 + iMonth%10 + "-" + iDay/10 + iDay%10;
}
}
Whenever possible, the code of a client should use the interface (rather than the class). So:
Date tDate;
public boolean iIsLeap(final Date pDate);
Date tDate = new DateImpl(2000, 12, 25);
Introducing an interface as well as a class declaration is preferable because:
Cymerman ([6]) says: ‘The only drawbacks to this scheme are the fact that there is some overhead associated with the creation and casting of objects, and the fact that more code is required to first specify the interface and then code the class that implements the interface. These two drawbacks seem insignificant, though, compared to the vast number of benefits.’
The book 'The Java Programming Language' by Arnold, Gosling and Holmes ([1]) says: ‘Any major class you expect to be extended, whether abstract or not, should be an implementation of an interface. Although this approach requires a little more work on your part, it enables a whole category of use that is otherwise precluded.’ In their book, they produce a class with the header:
class AttributedBody extends Body implements Attributed
They say: ‘suppose we had created an Attributed class instead of an Attributed interface with an AttributedImpl implementation class. In that case, programmers who wanted to create new classes that extended other existing classes could never use Attributed, since you can extend only one class: the class AttributedBody could never have been created.’
In the book 'UML Distilled' ([7]), Martin Fowler writes: ‘Programming languages [other than Java] use a single construct, the class, which contains both interface and implementation. When you subclass, you inherit both. Using the interface as a separate construct is rarely used, which is a shame.’
In the 1990s, some useful work was done on understanding how complex systems are built: this work recognized the importance of the use of patterns. Currently, the principal book in this area is 'Design Patterns: Elements of Reusable Object-Oriented Software' by Erich Gamma, Richard Helm, Ralph Johnson and John Vlissides ([9]). These four people are affectionately known as the Gang of Four (or the GoF). In their book, they say: ‘This ... leads to the following principle of reusable object-oriented design:
Don't declare variables to be instances of particular concrete classes. Instead, commit only to an interface defined by an abstract class [or an interface in Java]. You will find this to be a common theme of the design patterns in this book.’On the WWW at [8], you will find an excellent document entitled 'ChiMu OO and Java Development: Guidelines and Resources'. Mark Fussell says: ‘Use interfaces as the glue throughout your code instead of classes: define interfaces to describe the exterior of objects (i.e., their Type) and type all variables, parameters, and return values to interfaces. The most important reason to do this is that interfaces focus on the client's needs: interfaces define what functionality a client will receive from an Object without coupling the client to the Object's implementation. This is one of the core concepts to OO.’
Stroustrup ([16]) says: ‘The importance of the abstract class concept is that it allows a cleaner separation between a user and an implementer than is possible without it. An abstract class is purely an interface to the implementations supplied as classes derived from it. This limits the amount of recompilation necessary after a change as well as the amount of information necessary to compile an average piece of code. By decreasing the coupling between a user and an implementer, abstract classes provide an answer to people complaining about long compile times and also serve library providers, who must worry about the impact on users of changes to a library implementation. I have seen large systems in which the compile times were reduced by a factor of ten by introducing abstract classes into the major subsystem interfaces.’
Although this programming style encourages the client to use the interface rather than the class, the client is still using the class if it has to create an instance of the class:
Date tDate = new DateImpl(2000, 12, 25);
Suppose we now need to represent people and the constructor for the class PersonImpl needs to create a DateImpl object for a person's date of birth:
public PersonImpl(String pName, int pYear, int pMonth, int pDay)
{
iName = pName;
iDateOfBirth = new DateImpl(pYear, pMonth, pDay);
}
Including this code in PersonImpl means that it is dependent on DateImpl. If we make a change to the DateImpl class, we will need to recompile (and re-test) PersonImpl (as well as DateImpl).
There is one other problem. Suppose we now wish to switch to using some other class that implements the Date interface. We need to detect all the occurrences of:
new DateImpl( ... )
and change them to create instances of the new class. One of the principles of software engineering is that the commitment to some decision should be made in one place and not all over the place.
One way to do this which also overcomes the recompilation problem is to use the factory pattern (as described in [9]). We can introduce an interface (e.g., Factory) and a class (e.g., FactoryImpl) that are responsible for creating objects. They could have a method called createDate:
public Date createDate(final int pYear, final int pMonth, final int pDay)
{
return new DateImpl(pYear, pMonth, pDay);
}
Clients should be written in terms of this method. For example, PersonImpl's constructor contains:
iDateOfBirth = new DateImpl(pYear, pMonth, pDay);
iDateOfBirth = iFactory.createDate(pYear, pMonth, pDay);
where iFactory is a variable of the interface type Factory.
If the FactoryImpl object is created in the program's program class, then only the program class, FactoryImpl and DateImpl will need to be recompiled if the code of the DateImpl class needs to be changed. Or, if FactoryImpl chooses to use some class other than DateImpl, then only the program class and FactoryImpl will need to be recompiled.
In their book 'Exploring Java' ([12]), Niemeyer and Peck say: ‘Interfaces define capabilities, so it's common to name interfaces after their capabilities in a passive sense. Driveable is a good example; runnable and updatable would be two more.’
In the book 'Java Design: Building Better Apps and Applets' ([2]), Coad and Mayfield say: ‘Requiring interface names to end in able or ible is a bit too complicated a convention. ... Choose whatever prefix convention you prefer: I, I_, Int_; whatever. We prefer I.’
In 'ChiMu OO and Java Development: Guidelines and Resources' ([8]), Mark Fussell says: ‘Interfaces should be given no suffixes or prefixes: they have the normal name space. Classes are given a suffix of Class if they are meant to be instantiated or are given a suffix of AbsClass if they are an abstract class that provides inheritable implementation but is not complete and instantiable by itself.’
In my teaching, I follow Fussell's advice for interfaces and use a suffix of Impl for classes.
This document has made some suggestions about the ways in which classes should be coded. It has also shown how a Java interface declaration can be used to separate out the interface and implementation aspects of a class.
The document also points out that this material is not usually taught in books that teach Java. The document is really a plug for 'Understanding Java', the author's book on Java ([5]).