This blog entry is not one of mine. I have the pleasure of sitting back and letting someone else do the work! Ladies and gentlemen, this blog is written by ..... my wife!
I have recently changed job, in my previous job our Senior DBA, also my husband, and better known to all of you as Fatherjack used to nag me like crazy about my lack of comments. Even when I did comment it wouldn't be good enough and I couldn't understand what I was doing wrong.
Most of the work I have been doing since I started my new role has been investigating scripts, the systems are made up of various databases which pass data between other servers and additional databases and I have to try to track the data back and how it gets from source to final output.
The legacy scripts have little or no comments, however my new boss has very stringent rules on commenting and provides his team with clear guidelines on what is expected and the scripts that use his guidelines are excellent. However, this is not the case with legacy scripts which go back up to 10 years, which is 8 years longer than my boss. The comments, if there are any, state the obvious, for example,
-- this inserts A into B
INSERT INTO TableA
SELECT Name
FROM TableB
I understand this I can read the TSQL! What I want to know is why is it doing it. Why is it getting the data from A and putting it in B, what's the purpose of this script?
I am a firm believer that all scripts should start with a clear set of guidance to show the purpose and of course when and why it changed, for example:
/********************************************************************
Description:
Purpose:
Created On:
Created By:
Version
Date Updated Updated By Changes Made Reason for change
********************************************************************/
Then each part of the script should explain what it's individual purpose is. For example:
/* Looks for duplicates in table x and stores them in a temporary table for later use */
The other part of commenting that I think is equally important, is that when a change is made to a script that not only is the version in the header fully updated, but also where the change is made is also commented fully, especially when code is no longer required, this should not be deleted but just commented out.
/********************************************************************
Changed: March 2011 by Joe Bloggs
To amend the where clause to allow products that begin with 'C'
********************************************************************/
By following these very simple guidelines those people who come in after you to look at your code have got a better than average chance of working out what you were doing and why you were doing it. Sorry Fatherjack, I realise the error of my ways now and confirm that I will no longer leave my scripts with little or no comments.