Sql-server – With the advent of integrated source control, do stored procedure changes still need comments

source controlsql serverstored-procedures

Back in the old days, my team had a policy that any stored procedure modification required comments in two places:

  1. Top of the stored procedure with an overall summary of the changes
    made
  2. Comments on each line where the change was made

It typically looked like this:

CREATE PROCEDURE usp_Test
/*****************************************************************
The purpose of this stored procedure is to get data.
Created by 8kb 2001-01-01
Modified: removed OR clauses from JOIN statement..8kb 2001-06-01
******************************************************************/
AS
BEGIN

SELECT * 
FROM t1
JOIN t2
ON t1.colA = t2.colA
-- Removed OR clause..8kb 2001-06-01
-- OR t1.ColB = t2.ColB

END

But now with integrated source control, I can summarize the changes in the source control and then use the compare / diff functionality to see the differences between the old and new versions.

Is there still value in writing line-by-line change comments in stored procedures that are part of integrated source control?

Best Answer

This might be fine for one change per module, but imagine how your code will look like after severol years of development.

Before version control was universally adopted, there used to be modules that were 95% history log and only 5% actual code. Fortunately version control automated out that inconvenience long ago.

I would completely get rid of change logs in comments - we are much more productive using modern tools. Besides, git and other version control tools allow you do do much more than see the log of changes if one file. For instance, they can will show you all other files changed in the same commit. Also they give you accurate information, while we cannot fully trust comments.

Related Question