4. Class Definition

Part of CS:2820 Object Oriented Software Development Notes, Fall 2015
by Douglas W. Jones
THE UNIVERSITY OF IOWA Department of Computer Science

 

Everything is a Class

The textbook has a chapter titled Everything is an Object, and in the world of object-oriented programming, that is true. When you look at a large programming problem and think about how to create code, every noun you find in the problem description is a very good candidate for the name of either an object or a class of objects in the program that solves that problem.

For example, when you look at the screen of a computer, you typically see windows, icons and a cursor on that screen. An object-oriented implementation of the window manager for that computer will almost certainly be built on classes with names like Window, Icon and Cursor. If the window manager only supports one screen, there will probably be an object called screen. if the window manager supports multiple screens. There may well be a class, Screen, with one object of this class per screen, and possibly an object named currentScreen that names the object that that the user is currently focused on because the cursor is there. By convention, Java class names are almost always capitalized, while object names are usually in lower case -- there is nothing universal about this convention!

In our road-newtork example, there will be classes like Road, Intersection and Vehicle. In our logic-circuit example, there will be classes like Gate and Wire. In our neural-network example, there will be classes like Neuron and Synapse.

The important thing to note in all of these examples is that we can actually construct a huge amount of the framework of a program by analyzing the classes that make up the problem and their relationship to each other. Significant parts of this work can be done long before we know what algorithms are involved, before we know what output the program is supposed to produce, and before we know what input the program will take.

Class Definition in Java

We spoke in the abstract about classes of objects in our discussion of modelling a road network, a digital logic circuit and a neural network. Now, let's talk about implementing these classes in Java. Initially, we'll talk about these classes as pure data. We'll add behavior later.

If we are modelling a road network, we might begin with the following classes:

class Road {
	// indent to here between braces
}

class Intersection {
}

An aside on code format

Note in the above that the closing brace for each block is aligned under the keyword that opened the block, while the opening brace is at the end of the line (except perhaps for a comment). This indenting style is preferred both by our textbook's author and by me.

There is a matter of style here. Java is perfectly happy if we write this as:

class Road { } class Intersection { }

But that is not very readable once the program gets longer than one line. We could also write it as follows, keeping the opening and closing braces vertically aligned with everything between indented. This style tends to push code onto more lines, pushing code off the bottom of the editing window.

class Road
    {
	// indent to here between braces
    }

class Intersection
    {
    }

The style I use (and that the book uses) makes balancing brackets easy enough without pushing text off the bottom of the editing window.

Another question about code format is, how much should you indent. Short indents, for example, 4 spaces, allow deeper nesting than deep indents without adding pressure for longer lines. Tab stops in the Unix world are usually assumed to be every 8 characters, and this is the default supported by web browsers (when displaying preformatted text and .txt files. While you can set the tabs to other spacings, this can cause trouble, so the best bet is probably to leave the tabs at their default of 8 spaces and then, if you want to use shorter tabs, use the space bar and not the tab key.

But, the human mind can only digest a certain amount of complexity before it is overwhelmed. If your program really needs more than 4 or 5 levels of indenting, it may be too complex to understand and perhaps it should be broken up into digestable components.

Similar arguments suggest that long lines are not a good idea. Yes, the 80 column default for terminal windows is directly descended from the fact that punched cards have 80 characters each (a standard dating back to about 1928). This may sound like an archaic reason for the default length of a line, but this standard is based on the length of a line of text on a typical page of typing paper. That, in turn, is based on experience with easy readability. When pages get wider than about 80 characters, it gets difficult for the reader to track from the end of one line to the start of the next. When faced with wide pages, for example, in newspaper publishing. people start using multiple columns of text of text that span a wide page. Keep this in mind when you are tempted to simply widen your editing window and write really long lines of code.

Back to the road network

Regardless of how you indent it, the code given above is a framework, but we can store this in a file and start testing immediately. Consider using the file RoadNetwork.java

Of course, we ought to document this file with appropriate commentary, so right up front, we'll add some notes:

// RoadNetwork.java
/**
 * Classes needed to describe a road network
 * @author Douglas Jones
 * @version -1?
 */

/**
 * Roads are one-way connections between intersections
 * @see Intersection
 */
class Road {
}

/**
 * Intersections join roads
 * @see road
 */
class Intersection {
}

The above commentary uses the javadoc style of comments so that, later, when the program grows huge, we can use the javadoc tool to generate a documentation file from these comments. Note that Javadoc insists that the comment documenting any specific class, field or method be placed directly before that class definition.

Test this, save the file and use the javac command to make sure you have not messed up, then come back and start thinking about the next step. Let's start fleshing out the first class:

// RoadNetwork.java
/**
 * Classes that define the topology of a road network.
 * @author Douglas Jones
 * @version -1?
 */

/** Roads are one-way streets linking intersections
 *  @see Intersection
 */
class Road {
	float travelTime;         //measured in seconds
	Intersection destination; //where the road goes
	// Bug: do I ever need to know what intersection feeds this road
}

Recall that one attribute of each road is the travel time on that road. We added that, and we added a destination for that road. We also added a comment indicating a currently unanswered question: When looking at a road, do we ever need to know where that road came from? We will probably learn this much later, when we start thinking about algorithms.

It is a really good idea to adopt a convention of writing comments in your code to document bugs and other things you don't understand. If you consistently use a word like Bug to mark such comments, you'll have a very easy time seeing where your code still needs work.

An aside on capitalization

The above code fragment illustrates two issues: The first has to do with multiple-word variable names. It might have been nice to call one variable travel time and the other intersection destination, but in Java, you cannot put spaces inside an identifier. Other languages differ. In Fortran (the oldest high-level programming language), spaces are allowed in identifiers. In fact, in Fortran, all spaces are ignored, so they can be added at random.

An alternative to the style used in the code here (and in the textbook) is to use underscore as a space character in identifiers, for example, travel_time. This is a very popular style.

The style used in the text, and here, has been called StudlyCaps as if there is something masculine about squeezing out the spaces and capitalizing the first letter of each word, and also BiCapitalization.

The secnd issue surrounding the use of capital letters is a matter of convention: Here, the first letter of each class name is capitalized, while this is not done for variable names. When you define a new symbol, you can capitalize it any way you want, but conventions can improve readability.

So why aren't the names of built-in classes like int and float capitalized? There are two explanations:

First: We could claim that this is to emphasize the fact that int and float are not quite first-class classes. If a Java object is from a first-class class, it inherits a large number of attributes from the superclass of all classes. This has a high cost. Objects of built-in classes like int and float don't inherit these attributes. They have much more limited semantics in order to allow very efficient execution.

There is a full-scale class, Integer, that does everything that class int does, but more slowly. Each Integer has a single field of type int. Similarly, there is a class Float. These classes are useful because they contain a number of attributes and methods supporting the built-in classes.

Second: We could give the actual explanation. The type names int and float come from C and C++. Java didn't change things that worked just fine in those older languages.

Back to the road network

We can continue fleshing out our road network by adding comments to the definition of an intersection. We have some problems to solve here: How does one include a set of outgoing roads in a class? How does one create a class that comes in several types -- uncontrolled intersections, intersections where some road has a stop sign, intersections where all incoming roads have stopsigns? Does the intersection even need to know the identities of its incoming roads?

/** Intersections join roads
 *  @see Road
 */
class Intersection {
	// Bug: multiple outgoing roads
	// Bug: multiple incoming roads
	// Bug: multiple types of intersections (uncontrolled, stoplight)
}

Class vehicle has the potential to have attributes like cargo capacity and passenger capacity, but those depend on why we are building the model. Initially, our biggest question about vehicles is, does the vehicle need to know its current location? The answers to these questions depend on how we use the model, but we need to go quite some distance before that matters.

/** Vehicles travel on roads through intersections
 *  @see Intersection
 *  @see Road
 */
class Vehicle {
	// Bug: what are the relevent attributes of a vehicle?
	// Bug: do I need my current location?
}

Finally, as mentioned in the previous lecture we need to worry about events. At the very least, events represent arrival of vehicles at intersections, but there may be other classes of events such as departure from intersections. Vehicles in an intersection might, for example, block that intersection until they depart.

/** Events mark arrival of vehicles at Intersections
 *  @see Intersection
 *  @see Vehicle
 */
class Event {
	float time;         //when the vehicle arrives
	Intersection place; //where vehicle will arrive
	// Bug: is this right?  There may be many queues at intersection
	// Bug: how do we know which queue the road leads to?
	// Bug: do vehicles spend time in intersections?
}