Okay, here is a pet peeve of mine, I think every stored procedure, function, view etc. should all contain a block of code I refer to as a preamble. If yours doesn’t I strongly recommend you start adding it. It drives me crazy when I see code with no documentation of any kind telling me what it is for and when it was written or changed.
Why? A preamble documents the use, need, and changes for the code. It also leaves bread crumbs as to how why and what you did. I don’t know about you but I may code something and not have to change it for two years. When I do, I then think back and say why did I do that or who changed this code last. Working as a lone DBA, leaving bread crumbs was critical as I constantly jumped from task to task.
Above is the example of my preamble I use for all code I write. It tells who wrote it, what it is, what it is called by, how to run it, and lists any changes done to it. I find one of the most helpful items on this is the Run documentation. Here I place an exact run statement. It will show how the parameters should look and gives me a quick way to test it.
There are a million and one reasons as to why you should be doing this in your code. If you’re not doing it just take a second and start doing it. You’ll thank me for it later.
One Response
I like the idea of a preamble, but I don’t think changelogs, create dates or author names belong in there. That’s what source control is for.
I know storing schema and stored procedures in source control is a subject many have strong opinions on, and I know its not always possible to start doing if you are a consultant inheriting an existing system. So if source control isn’t going to happen the change log in the preamble makes sense.
That being said, when I am working with code actually in a source control system be it stored procedure or app code, I will go out of my way to both add headers to each module, and delete any reference to a date a change happened, the person that made a change, and blocks of commented out code. All of that information is available in the commit log, and by making it the only place that information is available, it forces developers to become familiar with their version control system.
It also makes the code and remaining comments more succinct and readable.