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.

There is exactly one case where I would do this, namely as part of a warning for future programmers: “Don’t call function foo() here directly; this has caused bug #1234, namely …”, and then a short description of the bug follows.

And if the code has changed in a way that there is no temptation to call foo() directly, remove that comment. It would only irritate and blow up the code.

It is an altogether horrible practice. It adds effort in order to achieve an effect that is pure duplication; in other words, the only thing that it adds over just using commit logs is the possibility of creating inconsistency. Your source files become cluttered with unlimited amounts of stuff that you never look at.

The only upside I can discern at all is that you could reconstruct the source history without access to the version control, e.g. when studying a printout. But very few people are competent enough to follow the intricacies of software development, while simultaneously unable to understand version control.

No.

That’s what people did before they used a version control system (i.e. when source code was just backups in zipfiles).

It is, IMHO, a very bad idea. After revision number 100, you will have 90% comments and 10% code. I would not consider that as clean and readable.

The only point in this I see is when you have to interchange your code between SCCs and, for whatever reason, you cannot transfer the history between the two systems (but even when you save the history comments that way, you will loose the diff history as well, so saving the comments will only help you a little).

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 my database 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.

One of the points in the Joel test is

Do you have a bug database?

Such information might be kept in a bug database if you think they’re important, but they would only be noise in comments.

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 isn’t any 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 this file, can give you an idea about how deep you need to dig into the history and possibly looking at the diffs. I had a request to “Change back to the original formula.” I knew 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.

If you have no VCS with commit messages, and no bug tracking system with an option for you to leave comments, it’s one option, and not the optimal one, to keep track of changes.
Better to have a spreadsheet with that information, or if you’re in an environment without such “luxuries”, a text file sitting somewhere near your sources.
But I’d strongly recommend if you’re in such an environment to start building a case towards investing in a VCS and bug tracking system 🙂

I think there are other elements to this discussion that are often forgotten but are cases where some revision comment is expeditious to a team.

When working in a team environment with a shared code base and where several team members are potentially working in the same areas of code, putting a short revision comment in the correct scope (method or class) indicating a change was made can be very useful for quickly resolving merge or checkin conflicts.

Likewise, when working in an environment where several (feature) branches are involved, it makes it easier for a third person (build master) to identify what to do to resolve potential conflicts.

Any time you have to get away from the IDE and ask someone why they changed something, it is disruptive to both team members’ productivity. A quick note in the correct scope can help abate or eliminate most of this interruption.

Keep this in mind – the code is often around longer than the tools that support it. Said differently, the issue trackers, version control and all the other scripts will evolve over the course of development. Information gets lost.

While I do agree, file clutter is annoying, opening a file and understanding its history without resorting to using the tools, has always been very helpful – especially if I’m maintaining the code.

Personally, I think there is room for both the tools and in-code log.

No, it is not a good practice to track your bug fixes as comments in the code. This only generates clutter.

I’ll also say the same for the copyright message that you mentioned. If no one outside your company is ever going to see this code, there’s no reason to include a copyright message.

If you are using version tracking software (Git, SVN, etc.), then you should include those notes in your commit messages. No one wants to dig through the headers of every code file to generate release notes or see an overview of what changes were made. These change logs should all be stored together, either in your version tracking history, your defect tracker, or both.

If you’re looking for a good read on this subject, I recommend chapter four of Clean Code.

I know Git doesn’t do this and the simple answer is “why on earth would it go there?”

It’s a less modular design in general. Under this solution, now files are some mix between content and meta-data. Amazon S3 is another example of a service for storing files that doesn’t add YAML front-matter or the like to files.

Any consumer of a file is required to process it through the version control system first. This is tight coupling, e.g. your favorite IDE will break if it does not support your VCS.

I definitely wouldn’t put such information at the start of the file – usually such a thing belongs into a ticket system.

There are however some cases where references into the ticket system and / or other documentation make sense. For instance, if there is a lengthy explanation of the design, or description of alternatives. Or information how to test things, or explanations why it was done exactly that way.
If that’s short, it belongs into the file itself; if it is long and / or is about a larger picture, you’ll probably want to put it somewhere else and reference it.

The project I am currently assigned to at work had this type of bug numbers list at the start of every file; however, none of the developers still on the project append to it anymore. Most of them think it’s a useless waste of space, as it is far inferior to tracking bug commits to a file using our version control system.

In certain critical files that have undergone many fixes and enhancements, these lists have become so large you have to scroll past them to get to the code. When greping these lists can result in several false positives as a short bug title or short description is listed with each.

In short, these lists are at best useless and at worst a massive, chaotic waste of space that makes code harder to search through and locate.

Any bug information directly associated to a piece of code, become irrelevant when the integrity of the whole change is modified by a successive fix.

It used to be common to add info in the function summary when we had to rely on external tools (say javadocs) to create release notes from the code.
It is mostly useless or redundant with modern version control tools.

It could only make sense as a comment in a very modular piece of code, if one has to resort to some obscure or non stellar coding which future developers would be tempted to change – unaware of the reason behind it – like in a workaround to a library bug/shortcoming.