CHAPTER 14 ■ GOOD (AND BAD) PRACTICE
This problem can be eased to some degree by providing a centralized configuration file or class so
that settings can be changed in one place, but even then installation can be a chore. The difficulty or
ease of installation will have a major impact upon the popularity of any application you distribute. It will
also impede or encourage multiple and frequent deployment during development.
As with any repetitive and time-consuming task, installation should be automated. An installer can
determine default values for install locations, check and change permissions, create databases, and
initialize variables, among other tasks. In fact, an installer can do just about anything you need to get an
application from a source directory in a distribution to full deployment.
This doesn’t absolve the user from the responsibility for adding information about his environment
to the code, of course, but it can make the process as easy as answering a few questions or providing a
couple of command line switches.
For developers, installers have the further virtue of memory. Once an installer has been run from a
distribution directory, it can cache many of its settings, making subsequent installations even easier. So
the second time you install from a distribution directory, you may not need to provide configuration
information like database names and install directories. These are remembered from the first
installation. This is important for developers who frequently update their local development space using
version control. Version control makes it easy to acquire the latest version of a project. There is little
point, however, to removing impedance from the acquisition of code if you have a bottleneck restricting
its deployment.
There are various build tools available to the developer. PEAR, for example, is, in part, an
installation solution. Most of the time, you will use the PEAR installer to deploy code from the official
PEAR repository. It is possible, however, to create your own PEAR packages that can be downloaded and
installed by users with ease. The PEAR installer is best suited to self-enclosed, functionally focused
packages. It is relatively rigid about the roles and install locations of the files a package should contain,
and it tends to concentrate upon the process of placing file A in location B. I cover this aspect of PEAR in
detail in Chapter 15.
If you need greater flexibility than this, as you might for application installation, you may prefer an
installer that is more flexible and extensible. In Chapter 19, I will look at an application called Phing. This
open source project is a port of the popular Ant build tool that is written in and for Java. Phing is written
in and for PHP, but it’s architecturally similar to Ant and uses the same XML format for its build files.
Where PEAR does a few things very well and offers the simplest possible configuration, Phing is
more daunting at first, but with the tradeoff of immense flexibility. Not only can you use Phing to
automate anything from file copying to XSLT transformation, you can easily write and incorporate your
own tasks should you need to extend the tool. Phing is written using PHP’s object-oriented features, and
its design emphasizes modularity and ease of extension.
Documentation
My code is so sparse and elegant that it doesn’t need documenting. Its purpose is luminously clear at the
slightest of glances. I know your code is the same. The others, though, have a problem.
All irony aside, it is true that good code documents itself to some extent. By defining a clear interface
and well-defined responsibility for each class and method, and naming each descriptively, you
communicate your code’s intent. However, you can improve the transparency of your work still further
by avoiding unnecessary obfuscation: clarity beats cleverness unless cleverness brings with it immense,
and required, gains in efficiency.
The naming of properties, variables, and arguments, too, can play a tremendous role in making your
code easy for others to read. Choose descriptive names, where possible. I often add information about
the type of a variable to the name—especially for argument variables.
public function setName( $name_str, $age_int ) {
//...
}