CHAPTER 14 ■ GOOD (AND BAD) PRACTICENo matter how clear your code is, though, it can never be quite clear enough on its own. You have
seen that object-oriented design often involves combining many classes together in relationships of
inheritance, aggregation, or both. When you look at a single class in such a structure, it is often very hard
to extrapolate the bigger picture without some kind of explicit pointer.
At the same time, every programmer knows what a pain it is to write documentation. You tend to
neglect it during development because the code is in flux, and really your project is about getting the
code right. Then when you have reached a point of stability, you suddenly see the enormity of the task of
documenting your work. Who would have thought that you would create so many classes and methods?
Now your deadline is looming, so it’s time to cut your losses and concentrate on quality assurance.
This is an understandable but shortsighted attitude, as you will discover when you return to your
code for a second phase in a year’s time. Here’s a programmer quoted on the popular repository for
Internet Relay Chat (IRC) witticism http://www.bash.org:
<@Logan>: I spent a minute looking at my own code by accident.<@Logan>: I was thinking “What the hell is this guy doing?”Without documentation, you are destined to play out that story: wasting your time second-guessing
decisions you probably made for very good reasons (if you only knew what they were). This is bad enough,
but the situation becomes worse, and more expensive, when you hand off your work to a colleague.
Undocumented code will cost you expensive workdays, as your new hire is forced to pepper your code with
debug messages, and work her way through fat printouts of promiscuously interrelated classes.
Clearly the answer is to document and to do it as you code, but can the process be streamlined? As you
might imagine, the answer is “yes,” and once again, the solution is borrowed from a Java tool.
phpDocumentor (http://www.phpdoc.org/) is a reimplementation of JavaDoc, the documentation
application that ships with the Java SDK. From a coder’s perspective, the principle is simple. Add specially
formatted comments above all classes, most methods, and some properties, and phpDocumentor will
incorporate them into a hyperlinked web of documents. Even if you omit these comments, the application
will read the code, summarizing and linking up the classes it finds. This is a benefit in itself, allowing you to
click from class to class and to observe inheritance relationships at a glance.
I examine phpDocumentor in Chapter 16.
Testing
When you create a class, you are probably pretty sure that it works. You will, after all, have put it through
its paces during development. You’ll also have run your system with the component in place, checking
that it integrates well, and your new functionality is available and performing as expected.
Can you be sure that your class will carry on working as expected though? That might seem like a
silly question. After all, you’ve checked your code once; why should it stop working arbitrarily? Well, of
course it won’t; nothing happens arbitrarily, and if you never add another line of code to your system,
you can probably breathe easy. If, on the other hand, your project is active, then it’s inevitable that your
component’s context will change, and highly likely that the component itself will be altered in any
number of ways.
Let’s look at these issues in turn. First, how can changing a component’s context introduce errors?
Even in a system where components are nicely decoupled from one another, they remain
interdependent. Objects used by your class return values, perform actions, and accept data. If any of
these behaviors change, the effects on the operation of your class might cause the kind of error that’s
easy to catch—the kind where your system falls over with a convenient error message that includes a file
name and line number. Much more insidious, though, is the kind of change that does not cause an
engine-level error, but nonetheless confuses your component. If your class makes an assumption based
on another class’s data, a change in that data might cause it to make a wrong decision. Your class is now
in error and without a change to a line of code.
And it’s likely that you will go on altering the class you’ve just completed. Often, these changes will
be minor and obvious. So minor in fact, that you won’t feel the need to run through the careful checks