Clear the clutter

I've seen this done before, both manually by authors and automatically by scripts and triggers integrated with version control systems to add author, check-in comment, and date information to the file.

I think both methods are pretty terrible for two primary reasons. First, it adds clutter and noise to the file, especially as these comments age and become irrelevant to the current state of the file. Second, it's duplicate information from what's already maintained in the version control system, and if you are using a modern version control system that supports change-sets, then it's actually losing information about changes.

If anything, consider integration with your defect tracking system. Some tools allow you to link a defect or task ID number in a check-in comment to an item in the tracking tool. If you have all of your defects, enhancement requests, and work tasks in the tool, you can provide linkage that way. Of course, this comes with the downside of a dependency on those tools for the project.

The case for oversharing

I see that everyone is opposed to the idea and gave a historical reason (pre source control era) of why people were doing it.

However in my current company, database developers are following this practice and they additionally tag the bug number around the piece of code. I sometimes find this helpful when you see a bug in the code and you can instantly find out the bug fix that introduced this issue. If we don't have that information in the db package it certainly won't be easy to find the root cause of that implementation.

Yes it clutters the code but it helps in finding the reason of why that piece of code is there.

Continental breakfast of information

Sometimes I have the slight feeling that programmers are horrified by redundancy, so they avoid having the same information accessible through different ways. That's very interesting, because programmers are typically also horrified by bad performance and therefore use caches in their programs. But caching bug numbers in the code next to the place where they are most useful is considered bad? Mmmh.

Clarification above all

I think you have two problems here. First, why should you purely rely on the diff when most systems allow you to enter revision comments? Like good code comments, you discover why the change was made and not just the change itself.

Second, if you have this capability, make it a good practice to put all of them in the same place. There is no need to look through the file for marked out lines of code that are no longer needed. Comments inside working code are there to tell you why it is coded this way.

Once you put this into practice, the habits formed make the code base easier to work on for everyone.

Associated bug and feature tracking, along with why you're changing the file, can give you an idea about how deep you need to dig into the history, possibly looking at the diffs. I had a request to "Change back to the original formula." I new right where to go within the revision history and only reviewed one or two diffs.

Personally, remarked out code looks like a work in progress for a problem that is being solved by trial and error. Get this mess out of production code. Being able to easily slip lines of code in and out only makes it easier to be confused.

Find more answers or leave your own at the original post. See more Q&A like this at Programmers, a question and answer site for professional programmers interested in conceptual questions about software development. If you've got your own programming problem that requires a solution, login to Programmers and ask a question (it's free).