Change History and Change Documentation

Question

I work on legacy systems, and I used to look at the change history of files or functions that change every release in the source code, for example:

// // Rev. No Date Author Description // ------------------------------------------------------- // 1.0 2009/12/01 johnc <Some description> // 1.1 2009/12/24 daveb <Some description> // ------------------------------------------------------- void Logger::initialize() { // a = b; // Old code, just commented and not deleted a = b + c; // New code } 

I'm just wondering if this way of documenting history is really used by many today? If so, how do you apply the changes in the source code - will you comment on it or completely delete it?

If not, what is the way to document these changes? If you use version control systems, does it follow that your source files contain clean source codes, with the exception of comments if necessary (there is no change history for each function, etc.)?

Answer 1

Just rely on your version control system. Yes, just clean source code. If the code is commented out, I delete it. If I'm not sure I will leave it there with a TODO comment. I am not adding comments to the reference tickets in the source, but in the commit message. You do not need to document in the code what it looked like.

Answer 2

Manual change histories are difficult to maintain, so they are almost always obsolete.

I trust the version control system to give me this information. In addition, it can be much more accurate, for example, with preliminary comments (who changed this line last).

I insert comments on reference tickets in the error tracking system directly in the source when I feel it is necessary, even if this information is also available in the commit message.

It makes sense to have a change / release notes file for each project (not for the source file), which is maintained and updated manually for each version.

Answer 3

Currently, the best way to document these changes is to allow your version control to do this, but it also means that you must enforce the rule that developers write meaningful comment comments, or at least some bug tracking numbers, so this will be easy understand what they did for what.

Answer 4

I have never seen a history of changes in code comments. At best, I saw Javadoc @version tags for documenting the version. The oldest version control method looks like this: logo2007-1.png, logo2007-2.png

Version control should be the best solution.

see also: http://betterexplained.com/articles/a-visual-guide-to-version-control/

Answer 5

I worked for a company that ordered this type of comment to all SPs that were in the database. I found this incredibly tedious and completely redundant compared to the notes we needed to get into our version control system.

The main use of inline comments was to verify that the deployment in the new environment was successful (e.g. production). It was also a tedious process and was used only because there was no other method.

I never found any use for inline comments like this elsewhere, and found that they caused a tiring headache causing work.

I would advocate a system in which source control manages comments and revision history, rather than code. This is one of the goals of the system and the best place for it. IMO