When working on a professional project, it’s very important that you think about
what you’re doing. Know your enemy—never underestimate him. Although your project
isn’t really an enemy, the point still applies. Know all your project’s specifications, its
target platform(s), its users, and never underestimate the significance of small problems
that you haven’t evaluated completely before moving on to other topics.
Judging from our experience, planning takes at least 50% of the development time;
the bigger the project, the more thoroughly you should develop its outlines.This prin-
ciple applies to contacting your customers and working closely with them on defining
an overall project outline, as well as talking with your developers about defining a
coding outline.The less effort you spend on consistency and maintainability, the
sooner you’ll run into problems when reopening old files and trying to fix bugs or
add new features.
Planning time isn’t necessarily proportional to a project’s size. As an example, think
about a search algorithm that you have to design.The application doesn’t have to do
more than basically crawl through a heap of information, extracting data according to
a set of rules. Let’s say that the data is already there, so setup and output won’t require
a lot of effort.The application will spend most of its execution time in its main
searching loop.The loop probably won’t even take more than 100 lines of code, but
choosing or designing an optimal algorithm for an optimal loop could easily take a
whole day.This little loop might be the most substantial part in your design phase,
while on the other hand you may create projects with a few thousand lines that have
been thoroughly planned in less than a day.
Similarly, let’s say you need a little script that lists all files in a directory.You could
hack it quickly so it would perform just this specific task, listing all files in a specified
directory.You wouldn’t have to worry about it anymore—the problem’s solved and
you can move on to other tasks, leaving your snippet behind. But another strategy
might be to take into consideration that at a later point—maybe even in a completely
different project—you’ll probably need a similar tool again. Just hacking directory
listers over and over when you need one, each for its specific task, would be a waste
of time.Thus, when first encountering such a situation, you should think about it.You
could create a separate module from the directory lister, allowing it to list different
directories, optionally recursing subdirectories, eventually even accepting wildcards.
You might create a bulletproof little function that would handle most special cases
and also handle everyday demands to a directory lister just perfectly.With this latter
method, after a few projects you would have a library of solid tool functions that you
could reuse safely and rely on, and that sometimes might strip down development
time significantly.
Of course, an ever-increasing number of freely available tool function libraries exist,
but these will hardly satisfy all your needs, nor will they be optimized for your special
demands. Some libraries are also just too heavy to carry around—having to parse a
few hundred kilobytes of extra code every hit might significantly decrease the perfor-
mance of your site. In this situation, it pays to be able to replace a sub-optimal solution
with a 100% optimal solution that you created.
Larger projects offer even more opportunities for problems due to lack of planning.
Late in development, you might encounter difficulties that you didn’t or couldn’t fore-
see because of the lack of work and time spent on the design.These difficulties might
be so severe that they require you to completely restructure the entire project. Imagine
a database-backed application that relies on an additional database abstraction layer.
The database abstraction layer accepts only textual data, but at a later point you notice
that you also need it to accept numeric data.You might enable it to accept numeric
data by workaround conversions, but at a later point discover that the workarounds
don’t satisfy your needs.The only thing you can do at this point is change the database
interface, which requires a rework of the abstraction layer as well as a check of all
calls to it in the main code—and of course the removal of the previously created
workarounds.
Hours or days of work spent on something that could have been avoided from the
very beginning—problems that often decide between success or failure, because time is
the most valuable resource that you will never have enough of.
The following sections guide you through most of the very basic, yet very impor-
tant practical issues of development: improving your code quality as well as basic
design and documentation issues. After covering these, we create an application pro-
gramming interface (API), taking the naïve, practical approach to familiarize you with
the new concepts, followed directly by an API creation from scratch, developing it the-
oretically “on paper” and then nailing down a few practical principles to help you
implement your next API—matters of style, do’s and don’ts, as well as a few tricks of
the trade.
