Revision histories and documenting changes

Question

I work on legacy systems and I used to see revision history of files or functions being modified 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 still being practiced by many today? If yes, how do you apply modifications on the source code - do you comment it or delete it completely?

If not, what's the best way to document these revisions? If you use version control systems, does it follow that your source files contain pure source codes, except for comments when necessary (no revision history for each function, etc.)?

Answer 1

Nowadays the best way to document these revisions is to let your version control do it, but that also means that you have to enforce the rule that developers write meaningful commit comments, or at least some bug tracking numbers, so it would be easy to figure out what they committed what for.

Answer 2

I've never seen revision history in code comments. At most I've seen the Javadoc @version tags to document the version. The oldest version control method is 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 3

Manual revision histories are hard to maintain, hence almost always out-of-date.

I trust the revision control system to give me this information. In addition to be correct, it can be much more precise, for example with pre-line annotations (who has changed that line last).

I do insert comments to reference tickets in the bug tracking system directly in the source when I feel that it is necessary, even though this info is also available in the commit message.

It does make sense to have a changes/release notes file per project (not per source file) that is manually maintained and updated for every release.

Answer 4

I used to work for a company that mandated this type of comment on all SPs that went to the database. I found it incredibly tedious and completely redundant over the notes we were required to enter into our source control system.

The main use of the inline comments was to validate that the deployment to a new environment was successful (like production). This also was a tedious process and was only used because there was no other method.

I have never found a use for inline comments like this anywhere else and found they only caused tedious headache inducing work.

I would advocate for a system where source control manages the comments and revision history and not the code. That is one of the purposes of the system and that's the best place for it. IMO.

Answer 5

Just rely on your version control system. Yes, just pure source code. If code is commented out I delete it. If I'm not sure I leave it there with a TODO comment. I don't insert comments to reference tickets in the source but in the commit message. You don't need to document in the code what it used to look like.