Does Your Code Have a Preamble?

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 thought on “Does Your Code Have a Preamble?

  1. I have adjusted my comments over time. Latest rendition:
    /*==============================================================================

    Procedure: [updPollingError]

    Schema: [dbo]

    Database: [CSATSurvey]

    Usage: DECLARE @CallDataID INT = 1

    EXEC [dbo].[updPollingError] @CallDataID

    Description: This procedure is used to delete a record for the Error.Polling table.

    Compatability: SQL Server 2012 (110)

    ================================================================================
    Rev Date Who What
    — ———- ————– ———————————————
    000 02-08-2017 John Couch Initial Revision

    ================================================================================
    Notes

    ==============================================================================*/

Leave a Reply

Your email address will not be published. Required fields are marked *