SQL Server Team-based Development - Red Gate Software

Chapter 2: Documenting your Database
down in front of some convoluted code, asked the rhetorical question, "God, what idiot
wrote this code?" only to find out it was me, some time in the past. By documenting, I
don't just mean the liberal sprinkling of inline comments to explain particular sections of
code. If you are coordinating a number of programmers on a project, then it is essential
to have more than this; you'll require at least an explanation of what it does, who wrote it
or changed it, and why they did so. I would never advocate presenting the hapless coderefactorer
with a sea of green, but with a reasonable commentary on the code to provide
enough clues for the curious. I'd also want examples of use, and a series of assertion tests
that I can execute to check that I haven't broken anything. Such things can save a great
deal of time.
Where the Documentation Should Be Held
Most database developers like to keep the documentation for a database object together
with its build script, where possible, so that it is easy to access and never gets out of
synchronization. Certain information should be held in source control, but only
sufficient for the purposes of continuous integration and generating the correct builds
for various purposes. This is best done by an automatic process from the main source of
the documentation. This primary source of the essential documentation should be, in
effect, stored within the database, and the ideal place is usually within the source script.
Source control cannot take away this responsibility from the developer. In any case,
source control, as devised for procedural code, doesn't always fit perfectly with database
development. It is good practice to store the individual build scripts in source control,
and this is essential for the processes of configuration management, but it doesn't provide
everything that's required for the day-to-day work of the database developer.
The obvious place to hold documentation is in a comment block in the actual text for
routines such as stored procedures, rules, triggers, views, constraints, and functions.
This sort of comment block is frequently used, held in structured headers that are
normally placed at the start of a routine, but acceptable anywhere within it. Microsoft
38