Code Documentation, tracking revisions

[dgs!]

I have been asked to better document my code whenever a revision has been made. In the past, I have always included detailed information in the heading of the program outlining each change, and then checked the revision into SVN. My thought being, if you want to see whats changed, DIFF the Current version with the previous version.
I'm not a big fan of 'junking up' programs with comments that date each and every change. Over time, these comments become meaningless and just junk up the code. Do I really care that Johnny changed line 456 back in 2010? How is that helpful? It's ancient history, who cares?!?

That being said, does anyone have a cool, concise way to document changes that makes them easy to find and doesn't junk up the code?

 

[T-Gergely]

SVN comments?

 

[dgs!]

Yeah, I'm all for making SVN do the work, but they want each line/area tagged has having been changed. To me, this is sissy programming... the fear that a change is going to break something. I use to do this 30 years ago when I didn't know what I was doing. Then someone invented version control software.

Here's one idea I came up with last night. Create a 'MOD_ID' (yyyymmdd) and leave that in the heading of the program next to the explanation of what changed in this revision. Then tag the changed line/area with the MOD_ID. Its significantly less junky, gives you the location of the change and the text of the change isn't mixed in with the code.
Sound good? Any other ideas?

 

[mike]

I agree with you that it clutters up the code. Unfortunately, the only other idea I have will probably get you into trouble

If it helps, where I work, some teams do similar to what you describe. Some code ends up with a commented out line similar to below. I don't see any value in it, but they like it and claim it helps them. If I were to do it, I might put the tags more to the right like column 130 so I don't see them.

-- get_payroll_dates(i_payroll_id); -- Rev3, Rev5, Rev8, Rev12, Rev24