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.

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 of this practice.

If this is good practice, what could be guidelines of this practice?

share|improve this question
add comment

6 Answers

up vote 13 down vote accepted

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.

share|improve this answer
    
+1 This seems to be the case for the jQuery issue comments. – Not having comments here would be seriously confusing. –  Konrad Rudolph May 2 '12 at 9:48
    
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. –  Mikko Rantalainen May 3 '12 at 11:16
add comment

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.

share|improve this answer
    
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? –  Sangdol May 2 '12 at 4:27
4  
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 May 2 '12 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. –  Benjamin Wootton May 2 '12 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 May 2 '12 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 May 2 '12 at 10:18
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
1  
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). –  Mikko Rantalainen May 3 '12 at 11:23
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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