Search
Home
Articles
Backup
Books
Certification
FAQ
Products
Replication
Scripts
Seminars
Training
TSQL

MSDN Fourms
Philippine SSUG
Fort Worth SSUG
Oklahoma City SSDG

Resume

MHS Enterprises
BlowFrog Software
FilAm Software
AcrylicAcetate.com
Bargain Humidors
Western Humidor

One of the things that I see very rarely is script headers and comments.  This is baffling.  Almost every development project I have ever worked on has had very elaborate version control systems, coding standards, commenting guidelines, and even templates.  For some reason, this was never carried through to the database.   Unfortunately, the database is the one place that needs this even more than an application does.  This is simply because a single application may only work with a small fraction of a database while a single database can have hundreds of applications going against it.  We comment, standardize, and document all of the code in our applications.  Everything that goes into a database is code also.  Just because it resides on a server and doesn't have a fancy GUI tool and OO stuff for it does not mean we should bypass this.

One of the functions of a DBA is to review all of the database code and modifications before it goes into production.  If the DBA does not approve, it does not get implemented.  Documentation and standards might seem to be very picky topics to hold things up for, but I strictly enforce this everywhere I go.  If a developer hands me a script that does not have a script header or comments, I won't even review the code.   It could be the greatest code since sliced bread, but if it doesn't have comments or a header it goes back.  Is this harsh?  Absolutely!  But, I can't tell you how many times I've had to modify a stored procedure, trigger, or modify a schema and the original developer is no longer around.  This forces me to spend a lot of time tracking down design documents, business requirements, and tracing code before implementing the change.  DBAs are a very expensive and very limited resource.   The more you can do to simplify maintenance and administration the better off your employer/customer/client is going to be.

Below is the script header that I always implement unless one already exists at one of my clients.  Even then by the time I'm done, their headers look very similar to this.

/************************************************************************/
/* Stored Procedure: <the name of the procedure>			*/
/* Creation Date: <when this was created>				*/
/* Copyright: <name of the company>					*/
/* Written by: <who created the proc>					*/
/*									*/
/* Purpose: <purpose of the script>					*/
/* 									*/
/* Input Parameters: <list any input parameters>			*/
/*									*/
/* Output Parameters: <list any output parameters>			*/
/*									*/
/* Return Status: <list any return codes>				*/
/*									*/
/* Usage: <a sample usage statement					*/
/*									*/
/* Local Variables: <list all local variables>				*/
/*									*/
/* Called By: <what this is called by: application, proc, etc.		*/
/*									*/
/* Calls: <anything this script calls>					*/
/*									*/
/* Data Modifications: <any modifications to tables>			*/
/*									*/
/* Updates:								*/
/* Date 	Author 		Purpose					*/
/* <this section is used to track changes to the script>		*/
/* 									*/
/************************************************************************/

There are two elements I am relatively lenient on: Copyright and Written By.  If you are writing packaged software, I strongly recommend adding this in.  This prevents someone from simply copying your code and reusing it without permission.  It does not protect the code as someone can still duplicate the functionality, but it does force them to take this effort.  I also usually don't fill in the written by section.   This is simply personal preference.  All of the rest of the information is vital to maintenance and administration.  By filling out a header like this, you give the person who has to modify your script every piece of information they need to understand your script.  To see an example, simply download any of the scripts that I have posted.

Michael R. Hotek

All content on this site, except where noted, represents an original work of Michael R. Hotek and is protected by applicable copyright laws. The SQL Server FAQ is the sole work of Neil Pike. No page, portion of a page, or download may be used for commercial purposes in whole or in part without the express, written permission of the applicable author.