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?
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.
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 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.
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
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.
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.
Or:
// 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.
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.
