![]() Microsoft had an attempt at a standard for doing it. 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. The obvious place to hold documentation within the SQL source is in a comment block in the actual text for routines such as stored procedures, rules, triggers, views, constraints and functions. The problem is in the duplication of effort if you wish to provide extra data to source control such as check-in comments. You can hold the documentation separately from the code in source control, of course, but it is difficult to match the convenience of having as much information accessible within the database. When documentation about code needs to be extracted, it is best done, where possible, by an automatic process. 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. The source code should be the canonical version of documentation where possible. Certain information should be held separately in source control, but only sufficient for the purposes of continuous integration and generating the correct builds for various purposes. Most database developers like to keep the documentation for a database object together with its build-script, where possible: That way, it is easy to access and never gets out of synchronization. Such thing can save a great deal of time. 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. I would never advocate presenting the hapless code-refactorer with a sea of green, but with a reasonable commentary on the code to provide enough clues for the curious. By documenting, I don’t just mean the liberal sprinkling of in-line 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. Many times, I’ve sat down in front of some convoluted code, asked the rhetorical question ‘God, what idiot wrote this code?’ only to find out it was I, sometime in the past. Even if you are working solo, and you operate a perfect source-control system, it is still a requirement that kicks in pretty soon, unless you have perfect recall. ![]() When you’re doing any database development work, it won’t be long before you need to seriously consider the requirement for documenting your routines and data structures. In this article I’ll show how to insert structured headers into SQL code, and attach them to various database objects, and show to extract the information from the database in a form that can then be used for whatever purpose you require. Once you have an effective way of providing details about the tables, views, routines, constraints, indexes and so on in your database how do you then publish this information in a form that can be used? ![]() ![]() The puzzle is in working out the most effective way of providing this detail. Automatic database generators can help, but cannot absolve the programmer from the requirement of providing enough information to make the database and all its routines intelligible and maintainable: This requires extra detail. You should never believe anyone who tells you that effective database documentation can be entirely generated from a database just by turning a metaphorical handle. In the absence of an obvious way of going about the business of documenting routines or objects in databases, many techniques have been adopted, but no standard has yet emerged. No sensible method for doing database documentation has either been provided by Microsoft, or properly supported by the software tools that are available. ![]() Most languages allow you to extract this information for the purposes of reporting, documentation, integrating with bug-tracking or source control, or providing tooltip help: SQL Server doesn’t. I like to keep as much information as possible together with the code I write, whatever language I use. IntroductionĬode likes to be surrounded by explanation. “Facts and Fallacies of Software Engineering” by Robert L. ‘Understanding the existing product consumes roughly 30 percent of the total maintenance time’ Documenting your SQL Server Database - Simple Talk Skip to content ![]()
0 Comments
Leave a Reply. |
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |