Can’t say this often enough. A lot of the things you need to do have already been done by the good folks at JavaSoft. Learning the API well is a good grounds for avoiding that deadly “reinventing the flat tire” syndrome -- coming up with a second-rate equivalent of a first-rate product that was available to you the whole time. This is, in fact, part of this book’s mission -- to prevent you from reinventing what’s already there. One example of this is the Collections API in java.util, discussed in the previous chapter. It has a high degree of generality and regularity, so there is usually very little reason to invent your own data structuring code.

There is a trade-off between generality (and the resulting reusability), which is emphasized here, and the convenience of application specificity. If you’re writing one small part of a very large application designed according to OO design techniques, you’ll have in mind a specific set of use cases. On the other hand, if you’re writing “toolkit-style” code, you should write classes with few assumptions about how they’ll be used. Making code easy to use from a variety of programs is the route to writing reusable code.

You’ve no doubt looked at the Java 2 online documentation in a browser, in part because I just told you to learn the API well. Do you think Sun hired millions of tech writers to produce all that documentation? No. That documentation exists because the developers of the API took the time to write Javadoc comments, those funny /** comments you’ve seen in code. So, one more bit of advice: use Javadoc. We finally have a good, standard mechanism for API documentation. And use it as you write the code -- don’t think you’ll come back and write it in later. That kind of tomorrow never comes.

See Section 23.3 for details on using Javadoc.

I can’t say this one enough either. Use subclassing. Use subclassing. Use subclassing. It is the best basis not only for avoiding duplication of code, but for developing software that works. See any number of good books on the topic of object- oriented design and programming for this. The topic of Design Patterns has recently evolved as a special case of “doing OO design while avoiding reinvention,” hence a merger of these two bits of advice. That book is a good place to start.

In Section P.4 of the preface, I listed Design Patterns as one of the Very Important Books on object-oriented programming, as it provides a powerful catalog of things that programmers often reinvent. It is as important for giving a standard vocabulary of design as it is for its clear explanations of how the basic patterns work and how they can be implemented.

Here are some examples from the standard API: