Unwrap the package statement's potential

Minimize project complexity and maximize code reuse

By Laurence Vanhelsuwé, JavaWorld.com, 02/21/03

Page 3 of 7

org.lv.lego.adt
org.lv.lego.animation
org.lv.lego.applets
org.lv.lego.beans
org.lv.lego.comms
org.lv.lego.crunch
org.lv.lego.database
org.lv.lego.files
org.lv.lego.games
org.lv.lego.graphics
org.lv.lego.gui
org.lv.lego.html
org.lv.lego.image
org.lv.lego.java
org.lv.lego.jgl
org.lv.lego.math
org.lv.lego.realtime
org.lv.lego.science
org.lv.lego.streams
org.lv.lego.text
org.lv.lego.threads

Note how most of these packages' logical content is self-evident as a result of carefully choosing appropriate and self-descriptive package subbranch names (compare to the java.* hierarchy). This is critically important in unlocking the reuse potential of reusable (generic) resources such as reusable logic, routines, constants, classes, and interfaces. Poorly named package branches, like poorly named classes/interfaces themselves, can confuse your intended user base and sabotage your resources' reuse potential.

At these deeper package levels, you again must be very careful about how you further organize your packages.

Here's Golden Rule Number 2:

If you end up with a hierarchy that degenerates, in places, into a linear listing, then you are failing to exploit the Java package feature correctly. The classic mistake is simply listing project packages under your top-level applications package branch, my equivalent org.lv.apps. This is a mistake because a linear list of projects is not hierarchical. Linear lists are hard for human brains to grasp long term; hierarchies, on the other hand, are a natural fit for our brains' neural networks.

Projects can always be categorized by a key criterion, and this criterion or attribute should reflect in your Java package hierarchy. As an example, here's how my org.lv.apps is currently subdivided:

org.lv.apps.comms
org.lv.apps.dirs
org.lv.apps.files
org.lv.apps.games
org.lv.apps.image
org.lv.apps.java
org.lv.apps.math

Obviously your subdivisions will most likely differ from mine, but the important point is to think big and always keep future expansion in mind. Deep package hierarchies are healthy. Shallow ones are not.

Where to store all those static utility routines

Once you've accepted the logical need for two fundamentally different types of classes (generic ones and application-specific ones), you're just one step away from solving another awkward problem: where to store those oh-so-handy, but totally non-object-oriented, static utility routines.

I always despair when I see Java code that contains completely generic facets embedded in application-specific classes. Say an e-commerce application relied on a class called Customer containing, among other things, the following method:

private String surroundedBy(String string, String quote) {
   return quote + string + quote;
}

The class Customer programmer included a utility method to produce a string, which is quoted: method surroundedBy(String, String). The method is declared private, presumably because the author judged the method to be a Customer class implementation detail. Since the method is also not declared static, it apparently follows that this method is deliberately declared as an instance method. Looks perfectly benign, or is it? What is wrong with this method?