T-Sql Code Header Comments
In this post I want to talk about the headers that are included in most stored procedures and because I often see requirements for writing T-Sql code that include something along the lines of “all procedures MUST be well commented and adorned with a template that lists each change”, sample procedures include templates such as:
or:
These are all taken from stack overflow: http://stackoverflow.com/questions/1085672/sql-comment-header-examples
These templates all impart a sense of professionalism and care has been taken to write correct comments and we all know that dutifully ensuring comments are correct help show how well the database code has been written, except that is rarely the case. The quality of comments bears no relationship to the quality of code, in fact code is compiled by a compiler so incorrect code can be detected, incorrect comments are ignored by the compiler just as much as correct comments.
There is one section in particular that is a problem, the change history – if you use source control you have a history of changes which can be validated and checked, however if instead you rely on the comments then you are relying completely on developers updating the comments correctly which is unlikely, either due to time constraints (i’ll fix this now and update comments later!) or potentially maliciously. If you then consider that the version history could possibly be incorrect then it can’t be trusted and if it can’t be trusted then it is irrelevant and is a waste of time.
Most templates include the name of the stored procedure, in case you don’t know how to find the name of each stored procedure is at the top of script, either after the word proc or procedure, it is sometimes surrounded by [ and ] or “‘s, if the name is in the comments then it might be after something like “Name:”, “Nombre: “, “Monkier:”, “Namesake: “, “Stage Name:” or something more exotic:
So if we use source control (which we should) then if we take the above we have a verifiable history of who the author is (they checked in the code), when the create date is (the date it was checked in), the history which includes both comments and actual diff’s can also be taken from source control.
The above code could have been written as:
Not everything is useless, there is a real case for showing example usages, especially when there are multiple parameters passed in and it is good to see what possible parameters can be passed in but I think that is about it. You may also wish to include a copyright banner in amongst the header comments which can be included to keep lawyers happy and can be happily ignored by everyone else.
I have come up with a list of common things I see in headers and how they should be handled:
Template | Replace With | Why? |
Name | Script Header | It is already in an obvious place, if the editor has colouring (everything other than notepad) then it is nicely highlighted |
Author | Source control history | It is verified and easily retrievable |
Create Date | Source control history | It is verified and easily retrievable |
Change History | Source control history | It is verified and easily retrievable |
Description | The stored procedure name | If the name of the stored procedure does not accurately describe the action that it does then rename it! |
In another post I would like to talk about comments within stored procedures but I think that is enough for now!