Design Decisions

Packages

All of the classes that make up the Player and Game applications are organized into three packages: bingo.player, bingo.game, and bingo.shared. This organization is straightforward and is seemingly an obvious choice: The code for the Player application goes in the code>bingo.player package, the code for the Game application goes in the bingo.game package, and all the classes that are used by both go in bingo.shared. Seems reasonable enough.
However, it's worth a few words to explain the benefits of this organization, why we didn't use more packages, and why certain classes were put in bingo.shared when they aren't actually shared.
Organizing the classes into packages provides these main benefits:

The first benefit is simply the benefit of having the classes organized and group. The BINGO game is comprised of about 50 classes. This is a substantial enough number to justify grouping them by functionality. If all of the classes were in a single package, then they'd also be in a single directory. It would be difficult to find classes and keep them straight.
By dividing the classes into packages, the classes can use Java's access levels to restrict or allow access to member variables and methods based on package membership. If all of the classes were in the same package, the classes wouldn't have the fine-grain control over access as they now enjoy. [PENDING: example of this?]
[PENDING: more?]

The BINGO classes could have been further divided into more packages: The exceptions and error handling classes could have all been separated into their own package. the "listener" classes could have been separated into their own package, or the UI classes could have been in their own package. When deciding on the package structure, we decided that three packages would sufficiently divide the classes into appropriate functional groups and those packages would also be sufficiently populated. We decided to use three packages because we felt that a further divisioin would splinter the classes unnecessarily. We used class names to help group related classes within the three packages (for example, all of the exception classes have names that end in "Exception").
Like other areas of object-oriented design, many decisions like this are purely a judgment call. It's more of an art than a science and reflects personal style. You will find many programmers making different choices in areas such as this one.
Some classes and interfaces that are in bingo.shared are only used by the Game application (such as Constants). And some classes and interfaces that are in bingo.shared are only used by the Player application (such as Utilities). So, why aren't these classes in the application specific packages?
The packages represent a conceptual organization as well as a practical one. A class that is used by only one of the applications but lives in bingo.shared is one that might be useful to other applications but is not directly manipulated by the code in the application in which it's used.
[PENDING: find out if there are other classes whose package is a bit unusual or interesting?]
[PENDING: anything else to say about packages?]

Subclasses and Other OO Design Decisions

talk about division of labor and the choice to isolate certain things from the RingMaster (which could do it all).
bingo.game.ControlPane subclasses JPanel (why not just use one?)
discuss parentage of thread subclasses (BallAnnouncer and GamesThread)
discuss parentage of ListenerThread hierarchy
discuss parentage of Exception hierarchy
discuss interesting and exemplary choices of access levels
discuss the Parameters abstract class (why we chose to make it abstract and the access permissions and the overriding done by its subclasses)
Make some classes final and discuss them?

Use of Interfaces

BagOfBalls is an interface so that you can swap in your own class (RandomBag)
"implements Constants" is interesting because there are no methods in Constants just constants....class gets direct access to them (GameParameters.java, RegistrarImpl.java, SocketGate.java) Applies equally well to States.java implemented by RingMaster
Some classes implement Serializable...why
Explain the *Listener interface and the hierarchy

Where does the following belong:
It's interesting how we designed the UI elements that update themselves based on broadcast messages from the Game. Where does this go? Is this an OO thing or a UI thing?
A thought: we should highlight somehow the intended function of some classes. For example in shared there are collection of UI classes and listener things that are grouped by functionality. Shared also contains miscellaneous "helper" classes. Perhaps we should further divide things into more packages? Even if we don't change the package structure, we have to find a way to make these relationships and functions more obvious...class names?

Putting It All Together