Take the 2-minute tour ×
Database Administrators Stack Exchange is a question and answer site for database professionals who wish to improve their database skills and learn from others in the community. It's 100% free, no registration required.

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?

share|improve this question
1  
Short answer yes. If I'm reading code I would love to have comments inside to code so I can see what each piece is doing more readily while I'm working on it. –  Zane Jan 11 '13 at 18:06
3  
Descriptive header can be useful, history in the header no, dated commented out sections (as per your OR clause) most definitely not. –  Mark Storey-Smith Jan 11 '13 at 18:43
add comment

2 Answers

up vote 4 down vote accepted

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.

share|improve this answer
add comment

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.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.