Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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

The comments would look something like this:

 MODIFIED    (MM/DD/YY)
 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?

share|improve this question

closed as primarily opinion-based by James McLeod, Bart van Ingen Schenau, amon, MichaelT, GlenH7 Feb 24 at 15:50

Many good questions generate some degree of opinion based on expert experience, but answers to this question will tend to be almost entirely based on opinions, rather than facts, references, or specific expertise.If this question can be reworded to fit the rules in the help center, please edit the question.

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. –  M. Dudley Feb 7 at 15:20
2  
Related: stackoverflow.com/questions/123936/… –  Brian Feb 7 at 18:04
5  
@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 Feb 7 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... –  dmckee Feb 8 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). –  Peter Mortensen Feb 23 at 12:56

16 Answers 16

up vote 104 down vote accepted

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.

share|improve this answer
2  
"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 Feb 7 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 Feb 7 at 13:31
7  
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 Feb 7 at 14:29
2  
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 Feb 7 at 18:46

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.

share|improve this answer

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).

share|improve this answer

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.

share|improve this answer

No.

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

share|improve this answer
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 Feb 7 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 :-( –  Carson63000 Feb 7 at 23:28

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.

share|improve this answer
18  
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 Feb 7 at 14:14
19  
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. –  rem Feb 7 at 15:03

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.

share|improve this answer
1  
See the example in the question - the comments would reference the bug database... –  Izkata Feb 7 at 13:42

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.

share|improve this answer

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 :)

share|improve this answer

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.

share|improve this answer

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.

share|improve this answer
3  
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 Feb 7 at 20:09
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. –  Jeffrey Hantin Feb 8 at 0:11

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.

share|improve this answer
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 Feb 7 at 20:03

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.

share|improve this answer

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.

share|improve this answer

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.

share|improve this answer

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.

share|improve this answer

protected by ChrisF Feb 8 at 17:34

Thank you for your interest in this question. Because it has attracted low-quality answers, posting an answer now requires 10 reputation on this site.

Would you like to answer one of these unanswered questions instead?

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