I saw many issue numbers from comments of jQuery code. (Actually, there were 69 issue numbers in jQuery code.) I think it would be good practice, but I've never seen any guidelines.

If it is a good practice, what are the guidelines for this practice?

6 Answers 6


In general, I would not consider it good practice. But in exceptional cases, it can be very useful, namely when the code has to do something unintuitive to fix a complex issue, and without any explanation there would be a risk that someone might want to "fix" this strange code and thereby break it, while explaining the reasoning would result in a huge comment that duplicates information from the issue.

  • +1 This seems to be the case for the jQuery issue comments. – Not having comments here would be seriously confusing. Commented May 2, 2012 at 9:48
  • 1
    I personally refer to issues in code only if the code deals with a workaround for an issue in third party code. References to your own issue tracker belong to version control system, not inside the code. For a big code base it could make sense to use similar references for internal workarounds, too. Commented May 3, 2012 at 11:16

I think it's enough to add the issue number to the commit message when you commit the related fix to your source control system.

For example:

Bug #203: Database connections no longer time out after 30 seconds.

I find that adding issue numbers, developer names or dates that changes have been made in the code just pollutes the codebase and should really be managed externally by your source control system.

  • I think you're right. Then, why do you think do jQuery committers put issue numbers on comments? Maybe it's special case for popular code? Commented May 2, 2012 at 4:27
  • 8
    I disagree. Comments are there to explain why the code is the way it is, when it's not obvious from the code itself. Bugs can give a great context for the "why" of code, so a link to a bug can be very helpful in understanding it. Having said that, I do like links to bug tickets in source control logs as well, but that serves a different purpose.
    – Jeroen
    Commented May 2, 2012 at 5:43
  • I think you should do both, but I don't think its enough on it's own to add these comments into source code control. You rarely even see those comments unless you go looking for them. Having these references much more visible can be useful IMO. Commented May 2, 2012 at 9:42
  • 1
    Jeroen: I disagree with you again. That is, if the fix of the bug is a quick and ugly hack, then you should comment on that and ref the bug. If the fix is a proper fix, it should actually explain why it is as it is itself. In the ideal case, there should be no reason for a comment of any kind, and a ref to the bug in source control is sufficient. If your fix is not self explanatory, you need to consider refactoring it.
    – martiert
    Commented May 2, 2012 at 10:01
  • If it were an implementation and not a bug, you would not see a comment. Why? Because evolution of the code is normal and even expected, so the implementation of a feature is not going to reference its task id unless circumstances were particular, contrary to bug fixing, which serves to quickly locate notable differences from the original for fixing problems. Otherwise, a programmer looking at the code might scratch his head for an hour trying to understand why it was done differently with respect to the rest of the code (and might change it back in the worst case scenario).
    – Neil
    Commented May 2, 2012 at 10:18

I completely disagree with the other posters here!

Code comments with tracking references can be a huge help for maintenance programming.

If I'm tracking down a bug and getting close to the area of the code, to see that it has recently been changed and have a link off to the context of the change is a god-send.

Yes we have source code control, but it can be quite slow to check files and modules individually. You want these things to jump out at you for recent changes.

I would probably deprecate them as I see really old ones in the code base, but there is very little down side to keeping more recent ones in and lots of potentially saved developer time if you use them smartly.

I actually think these little references to your bug tracking system are preferable to detailed comments in the code.

  • 2
    If you use some source/version code system that's worth using, your version control system can annonate every line of your code with the revision that changed it. For example, the default git gui blame <filename> provides a very fast GUI for browsing the code history if you use git. Using a tool to combine code comments with history allows much better documentation for the code than any inline comments ever can. That is, if you bother go write good commit messages (a good commit message should be roughly equal to an email message explaining why that patch should be applied). Commented May 3, 2012 at 11:23
  • If you start a project from scratch using a bug tracker, virtually all lines of code come from a user story or bug fix, then what? Do you comment all lines? Commented Oct 31, 2018 at 19:15
  • @Mikko Rantalainen I agree in the case when the project starts, but much too often the code get's spread out, copied, pasted somewhere else or moved etc. and then the vcs looses the code line <-> fix commit link and tracking it down takes too much effort.
    – Lutz
    Commented Jan 19, 2023 at 10:06
  • Have you tried git blame -C -C -M path/to/myfile.ext? Git can follow copied and moved lines nicely in most cases. Unfortunately, most other tools used for merging branches are not equally good but if you a have good text editor, it should support following moved or copied lines for its builtin git blame functionality. Since copying single lines may be computationally expensive operation, git gui blame requires you to select "Do Full Copy Detection" in its context menu to do this. Commented Jan 19, 2023 at 14:35

If you subscribe to a policy of "Clean Code", then you probably need to ask yourself if it is good practice to add comments at all. If the code can only be clarified with a comment, then sure, add one, otherwise you should be able to easily understand what your code does simply by reading it (provided you are using sensible names for your variables, methods, Etc.).

Regardless of your personal view about whether commenting is good practice or not, a comment should contain information that is of direct value to the code that the comment is referring to. In this case, the question is whether adding an issue number adds value to the code. The problem I see with adding the issue number is that you can have a section of code that might be modified heavily in order to satisfy several issues, and after a while, it could be impossible to correctly identify which changes related to a specific issue. Subsequent issues for example may require code relating to prior issues to be heavily refactored. This is perhaps an extreme example, however it does show how the issue numbers in comments in code can turn out to be pretty useless.

If you could guarantee that the situation I have just described would never happen, I'd still argue that the issue number itself is still pretty useless without a description of what the issue is about, and yet, all of this information really belongs in your issue tracking system and should need to be duplicated. A better place to note the issue number would be in your version control system as a commit comment. The advantage is that you can compare versions and see the code changes relating to a specific issue, while the issue number itself provides you with the identifier needed if you want to review the reason for the change in the code.

With all of this in mind, I'd suggest that it is not really good practice as such adding issue numbers into comments within your code.

  • Even with clean code, adding comments about implementation may be valuable. For example, in a code that needs to interact with 3rd party program, it makes a lot of sense to add a comment that the implementation needs to do X to be compatible with weird edge case behavior of that 3rd party program. The important part is to explain why the code is written as-is, not how the code is written because it can be read from the code or version history. Commented Jan 19, 2023 at 14:38
  • But function level comments (docblock) should be enough for most cases because you can create function called detectAndWorkaroundXIfNeeded() which is self-documenting on the calling site. For complex enough X, trying to encode it in the function name is not going to fly, though. Commented Jan 19, 2023 at 14:41

I think it's good practice to refer to an issue for further reading, while giving a short explanation in the comment itself.

I generally only add comments if there is something subtle or unintuitive in that piece of code. Since some subtle issues can't be explained completely in a few lines, and I don't want to add dozens of lines of comments, I'd add a short comment describing what this is trying to achieve, and refer to the issue for details.

For example:

// Verify MAC before checking the padding, to avoid padding oracle attacks
// See issue 123 for details

Where issue 123 describes how that attack might look like, and why the new code is immune to the attack.


// Using foo's algorithm here, since it fits out usage pattern best
// Check issue 345 for a discussion of possible algorithms, and why foo was chosen.

The main problem with putting issue numbers into your source is that you now have an external reference. So you need to be sure that you won't lose the issue.

  • I'd recommend linking to public documentation for cases like this, instead. Claiming that the current implementation is using "the best" algorthm is going to bit-rot in long run when better algoritms are found so you shouldn't write such comments. It's good to add comment that some sequence of code is to avoid padding oracle attack because then future developer will know not to touch the code without understanding what is padding oracle attack or how the existing code avoids that. Document why code is needed with a comment. Commented Jan 19, 2023 at 14:45
  • If it's just "this was easiest to implement" or "this was considered the most effective algorithm while it was written", it doesn't deserve a comment in the code. All code should always belong to one of those cases. Commit message is enough for such less important details. Commented Jan 19, 2023 at 14:46
  • Legend says that there's some value adding a comment saying "Notice! This section of the code has been tried to been rewritten 13 times to improve performance. If you try and fail, increase this counter." for code that appears easy to optimize but cannot be optimized in reality. It might be good idea to have a comment along those lines to avoid wasting more future work if the context is truly hard. Commented Jan 19, 2023 at 14:49

Including the issue number in commit messages can be very useful when your source code is wired up with continuous integration. Applications like TeamCity will pull that information out and allow for better reporting.

With the above said I'm not 100% sure it pulls from code comments. Including issue numbers in the code works well if the issue numbers are persisted (e.g. you don't change issue trackers) and you don't have a lot of issues for a given project.

It is probably more helpful if you describe the problem and the solution so the next developer doesn't need to look up the issue number. The compiler or minifier will just remove your comments before the code is released into the wild so there should be no impact on the end result.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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