Is it a good practice to put bug numbers in the file itself inside a header comment?

The comments would look something like this:

 abc 01/21/14 - Bug 17452317 - npe in drill across in dashboard edit mode

 cde 01/17/14 - Bug 2314558  - some other error description

It seems helpful, but is it considered bad practice?

  • 23
    The question I'd ask is "What can you do with embedded bug numbers that you can't already do with your bug database?" I can't think of any actual use cases. Commented Feb 7, 2014 at 15:20
  • 2
    Related: stackoverflow.com/questions/123936/…
    – Brian
    Commented Feb 7, 2014 at 18:04
  • 6
    @JensG That's why you put it in the commit message, and a log on the file will give you pretty much the exact same thing, but without cluttering up the file...
    – Izkata
    Commented Feb 7, 2014 at 22:45
  • 1
    @JensG And when you have corrected scores or hundreds of defects on a particular file? The obvious answer is that you periodically clear out the stale IDs, but then you are back to grepping the VC log... Commented Feb 8, 2014 at 1:16
  • 3
    This question is the subject of the Ars Technica article Should we list bugs in the header of a source file? (published 15 days after this question was posted). Commented Feb 23, 2014 at 12:56

16 Answers 16


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.

  • 3
    "and if you are using a modern version control system that supports change-sets, then it's actually losing information about changes." - can you elaborate please?
    – Geek
    Commented Feb 7, 2014 at 13:30
  • 10
    @Geek I'm not sure what to explain. If you look at a file that references a bug ID number, you don't see other files changes as a result of that same defect unless you search the files. That's what a change-set is - a collection of files checked in together.
    – Thomas Owens
    Commented Feb 7, 2014 at 13:31
  • 9
    I would also add that if you move to a new bug tracking system then those numbers all become instantly worthless. I've run into that at my current job where some comments have numbers from bug tracking software that hasn't been used in 10 years.
    – 17 of 26
    Commented Feb 7, 2014 at 14:29
  • 3
    So after changing to the new bug tracking system, they become as useful as if they were never there. But assuming they provided some value at some point, and provides no negative value now, why not do it?
    – Cruncher
    Commented Feb 7, 2014 at 18:46
  • @17of26 – I'd imagine you could link old bugs/issues to new ones, if thru no other mechanism than as a comment like "old issue tracker bug 1234". Commented Feb 8, 2014 at 2:20

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.

  • 19
    Maybe I'm a bit of a hardass, but if foo() shouldn't be called directly, then the code should be structured in such a way that it can't be.
    – MetaFight
    Commented Feb 7, 2014 at 14:14
  • 20
    Oh, I tried to write something as an example, to make the text more concrete - don't take me too literally. A better case would be a case where you used an external library, and the function you would normally use for a specific purpose had a bug. Then a comment "Don't call foo() here" would be reasonable.
    – user82301
    Commented Feb 7, 2014 at 15:03

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.

  • How many bugs exactly do you think are possible in one file and if there are that many its probably time for a rewrite.
    – Andy
    Commented Feb 24, 2014 at 0:02


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

  • 2
    which was a version control system of sorts (and one I've seen used operationally in software houses as short ago as 2006, and no doubt is in use somewhere today).
    – jwenting
    Commented Feb 7, 2014 at 14:05
  • 1
    @jwenting I've seen questions on this very site from people unfortunate enough to currently be working in shops where that is current practice :-( Commented Feb 7, 2014 at 23:28
  • We use a great source control system. No one but me puts comments in when checking in code. <shrug> I comment certain things (like PLSQL that isn't always tracked by SCM). I comment my code to explain, but never tie it back to particular bugs, but I always reference bugs in SCM commit comments when I check in. Hopefully eventually someone will appreciate it.
    – Pedantic
    Commented Feb 8, 2014 at 23:53

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.

  • 4
    Absolutely. 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.
    – JensG
    Commented Feb 7, 2014 at 20:09
  • There's often another way to get that information (on the project I'm working on, it would be right click > Team > Show Annotations to get the git blame of the current file), but the difference is, with comments there is discoverability -- they can jump out at you -- and with annotations, you have to consciously decide to go looking for them. Commented Feb 7, 2014 at 21:13
  • 1
    Think, decide, click, click, click, scroll. That's why I said "caching in code". If it's there, I just see it.
    – JensG
    Commented Feb 7, 2014 at 22:41
  • 2
    @JensG Interesting point of view. Caches can improve performance but they also have a carrying cost. If the cache has to be filled, updated, invalidated, flushed and so forth by redundant human effort I'd question the cost-benefit ratio, especially considering how terrible humans are at keeping such denormalized constructions in sync. Commented Feb 8, 2014 at 0:11

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.

  • 1
    See the example in the question - the comments would reference the bug database...
    – Izkata
    Commented Feb 7, 2014 at 13:42
  • @Izkata But that's the point. The database itself may have a "comment" field with the comment. The question is not about having a bug database or not, but about whether keeping that in the source file is a good idea. I think, even if they are comments, they should be kept in the database itself because that's what it's for. Commented Feb 7, 2014 at 13:46

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.

  • 3
    question is about comment in the beginning of the source file, right after copyright message - this has nothing to do with comments in the narrower scopes
    – gnat
    Commented Feb 7, 2014 at 20:03
  • All of the answers here are talking about just that, though. If I make significant changes to the entire class file (reorg or formatting fixing), would I not comment the class file as the scope?
    – StingyJack
    Commented Feb 10, 2014 at 13:23

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.

  • Copyright notices are also there to (slightly redundantly) put employees on notice that the file belongs to the employer. And perhaps discourages illegal sharing (even by employees), judging by how many people seem to think that copyright only applies if there is a notice. Commented Feb 9, 2014 at 4:56

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.

  • this does not seem to add substantial value to what has been already posted in prior answers
    – gnat
    Commented Feb 11, 2014 at 12:27

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.


Not the answer you're looking for? Browse other questions tagged or ask your own question.