Documenting the Database

Technical content that describes the tables and fields in your application's database represents the most important piece of documentation generated during your application's lifetime. In fact, the need for good documentation is the basis for one of my core programming beliefs: Project documentation is as important, and sometimes more important, than source code.

You may think I'm joking about this. Although you will (hopefully) find a lot of humor in the pages of this book, this is something I don't joke about. If you are developing an application that centers on database-stored user content, complete and accurate documentation of every table and field used in the database is a must. Any lack in this area willnot might, not perhaps, but willlead to data integrity issues and a longer-than-necessary development timeline. Figure 4-3 puts it another way.

Figure 4-3. Any questions?

Why do I think that database documentation is even more important than user documentation or functional specifications? It's because of the impact the document will have on the user's data. If you have a documented database, you can make guesses about the functional specification, and probably come pretty close. If you lack user documentation, you can always write it when the program is done (as if there was any other way?). But if you lack database documentation, you are in for a world of hurt.

If you haven't worked on large database projects before, you might not believe me. But I have. I once inherited an existing enterprise-wide database system written in Visual Basic 3.0. The source code was bad enough, but the associated undocumented 100-table database was a mish-mash of inconsistently stored data values. The confusing stored procedure code wasn't much better. Because there wasn't a clear set of documentation on each field, the six programmers who originally developed the system had each made their own decisions about what range of data would be allowed in each field, or about which fields were required or not.

Tracing back through the uncommented 100,000 lines of source code to determine what every field did was not fun, and it took a few months to complete it with accuracy. Because the customer had paid for and expected a stable and coherent system, most of the extra cost involved in replacing the documentation that should have been there in the first place was borne by my development group. Don't let this happen to you!