Every Stored Procedure Should Start with a Header

Code is an ever moving target. Version control and documentation only go so far, if they even exist. Sometimes all you have is the code in front of you.

This is why I always start stored procedures with a header.

Here’s a template as a starter:

/* **************************************************************
Name:           dbo.GetOrdersForClient
Called By:      Client web portal > order history
Description:    Returns details of all orders for a specific client for a given time period

Version     Date            Author          Description
1.0         2025-02-01      Andy B          PRJ-123 - Original version
1.1         2025-04-10      Andy B          BUG-456 - Change join from INNER to LEFT
************************************************************** */
ALTER PROCEDURE dbo.GetOrdersForClient (...)

Name seems redundant as we have the proc name below right? Well yes. But how many procs get copied and pasted and tweaked. This is primarily a check to make sure the object and header line up.

Called By is useful to know which areas of the system could be impacted by a change to this procedure, and which area to start testing the changes against too.

Description gives us brief context into what the procedure does and why without needing to dig into lengthy documentation.

Then we come to the version control. This could be where source control comes into play. It’s not always that easy. Different teams have their own challenges:

• for a very small team or business version, control may not be a priority or non existent. You still want to know what’s changed though as issues will be a larger distraction to a smaller team
• conversely in a large organisation, you can have multiple projects impacting the same procedure at the same time. With multiple branches deployed to different environments, these versions help you quickly see which version you’re dealing with

The version list is the most valuable part. What changed, when it changed, and why was it changed. Coupled with additional comments in the code showing where the change was made, this can make troubleshooting a bad release much faster:

    LEFT JOIN dbo.OrderStatus ...       /* v1.1 Change from INNER to LEFT JOIN */

Of course there are other details which could be included in the header too. Feel free to throw some of these in if they’re useful:

• Owner/Team, for a larger dev team
• Parameter information
• Return values
• Debug details such as example call
• Notes for known issues, warnings, etc.

You won’t always have the right tools, source control, or documentation. But a consistent header is a low-cost way to leave a breadcrumb trail—for yourself or anyone maintaining the code later.