Universal Programmers Toolkit: Care and Feeding of Your Code Collection

Groundhog Day: It's Déjà vu All Over Again

Even if you've worked on only a handful of projects, surely you must have found yourself writing and rewriting the same types of functions repeatedly. I'm talking functions to do date arithmetic, output strings in a common format, or connect to a database. These types of functions are either too high-level to be built into the language, too low-level to be in the libraries you've purchased, or simply project-specific.

 

Because you want to be able to reuse your code (even code that is project-specific), you put it into a reusable module; if you're really smart you wrote it in such a way that you could use it, relatively unmodified, on other projects.

 

But inevitably, like continental drift, over the years your source code becomes unavailable for a variety of reasons:

 

• you change jobs and you either didn't or couldn't bring the code with you
• you begin developing in a new language, environment or platform
• the code simply drops out of sight, surviving only on a long-forgotten backup tape, floppy, CD or other medium

 

And as surely as the sun rises in the morning and sets in the evening, you are faced—once again—with the dubious prospect of writing yet another library of utilities for string manipulation, database abstraction, security, error reporting, etc.

"Do you hear that, Mr. Anderson? That is the sound of inevitability"

Yep, it's unavoidable: regardless of how well your utility library code is written, it will have to be updated and eventually completely rewritten. But you can prepare for the inevitable by following these steps:

 

1. Write your utilities in advance (although in a pinch you can write them as part of a project that needs them)
2. Update, refactor or rewrite your libraries whenever necessary (preferably during the course of a project that makes use of them)
3. Go to step 2 (update, refactor or rewrite regularly).

 

Your library of utilities serves several basic purposes:

 

1. The foremost (and most obvious) purpose is to have a readily-accessible library of code you can use in existing projects

 

2. A less obvious purpose is to have a blueprint for algorithms that you can port to other languages. For example, you may not need a string library for the projects you're working on now but what about the day you do need one? It'll be far easier to port your code from Language A to Language B than to write it from scratch in Language B.

 

3. Last, but perhaps most important, your libraries serve as a layer of abstraction between your application and:
1. compiler-specific symbols, constants, variables and functions
2. language-specific features
3. third-party libraries

 

In other words, if you change from Compiler A to Compiler B, or from Language A to Language B, or your third-party libraries change (e.g. you switch from Template Library A to Template Library B), you won't have to spend time reformatting your application code that made use of those libraries. Instead, you'll have to change only your own libraries that serve as the interface between the application and the low-level stuff.

 

Important things to note:

 

• Make sure you own the code. Nothing is worse than having to walk away from code you've put your life into (although in practice, the dirty little secret of this industry is that "proprietary" code often makes its way into other companies' systems).

 

• Keep the code available. That means make sure you always have a machine-readable copy somewhere, in a modern storage medium.

 

• Don't hesitate to update your code. Every library can always use another nifty, useful function. Even if you use only it once, chances are you'll find a use for it in the future so you might as well add it to your library. Besides, any excuse to update your library is a good one.

 

• Keep it clean. The library should contain code that is as generic as possible. Instead of writing application-specific versions of each library, instead write application-specific wrappers that call the generic libraries. The hierarchy will look something like this:

 

1.      application interface (top level)

2.      business logic

3.      application-specific wrappers

4.      your low-level libraries

5.      built-in language/OS/environment funcs

So, Which Modules Will You Need?

Following are the types of modules that every programmer will probably have to write multiple times over the course of their career:

String Functions

You probably don't have to deal with this much if you're using a high-level language like C++, Perl or PHP but if you're using C or assembly then you'll almost certainly need a string library.

Date Functions

Sooner or later you're going to need your own date functions, even if they simply call existing language-specific or third-party libraries. For example, you may commonly output dates in the format "Wed Sep 05 2006 4:09 pm." Instead of littering your code with multiple calls like this:

 

$d = date_format($date, "w m d Y h:m a");

 

You'd do better to encapsulate that formatting in a function which becomes part of your library of date functions:

 

// MyDateFunctions.lib:

function my_date_format($d) {

return date_format($d, "w m d Y h:m a");

}

 

// MyApplication.main:

$d = my_date_format($date);

 

Database Abstraction Functions

I'm talking a scheme for managing persistent objects (and a data store) that has been abstracted to the point where the underlying storage method is irrelevant to the calling code. Specifically:

• create/read/update/delete objects from the data store
• refer to those objects in an abstract form (independent of the underlying storage method)

Security Functions

You know the drill: logins, passwords and encryption. Specifically:

• register a new user
• update a user's profile (change password, retrieve lost password)
• delete a user
• user log in and log out
• testing whether a user is logged in
• retrieving info about user who is currently logged in (if any)

Configuration Options

A universal way for your program to get/set defaults, whether hard-coded or kept in an abstract data store. Specifically:

• set a value
• get a value
• allow multiple values based on context (e.g. local/remote, debug/production, etc.)

Error Logging

Logging, tracking, reporting and other stuff related to errors. Specifically:

• log an error (with formalized levels, e.g. alert/warning/error)
• perform a stack trace and/or other low-level data dump
• pass errors around within your program so they can be handled appropriately depending on the context (logging to disk, printing on the screen, etc.)

What Else?

I've been intentionally vague about what exact features you should write for each type of module because this will depend to a large extent on the nature of the languages you use, the external libraries that are available to you, the projects you work on, and your own personal style.

Conclusion

Like any good craftsman, a good programmer will ensure their tools are always available and in good working order. Occasionally that means taking time out from "real" projects to work on your tools. Don't think of it as a waste of time, but rather an investment in your future.