With the advent of integrated source control, do stored procedure changes still need comments?

Question

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?

Answer 1

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.

Answer 2

Having it in the body as well makes it easier for me to see the list of changes in one place instead of having to look at the procedure and cull the history from source control. So it has value IMHO, but whether it is worth double maintenance in your case, I don't think that's a question this site can objectively answer.