Is it generally helpful to include JIRA issues in code comments?

Question

Once in a while, I leave comments like

# We only need to use the following for V4 of the computation.
# See APIPROJ-14 for details.

or

# We only need to use the following for V4 of the computation.
# See https://theboringcompany.atlassian.net/browse/DIGIT-827 for details.

My main concern with doing so is that it increases our dependence on JIRA, so those comments would be entirely moot if we were to migrate into another project management system. While I don't foresee that happening in the near future, I remain wary of the increased coupling of organizational components (in this case: code, code repositories and a project management system).

However, I do see the benefit of having references to documented design decisions and feature inspiration throughout the code base. As far as I can tell, the benefits are

1. a clear path to design decisions, which helps with debugging and ramping up on particular segments of unfamiliar code,
2. fewer multi-line comments, which makes code seem cleaner/less intimidating to new contributors,
3. a clear path to (potentially) current technical and non-technical stakeholders, and
4. a decrease in the number of "why is this here" questions because of the aforementioned.

Answer 1

I would try to avoid such comments. Although I think there is a place for them where you have a particularly annoying requirement. Which without, anyone might want to refactor the code. eg.

//must log to the database instead of standard logging, 
//stupid requirement from those crazy DBAs!! see TKCT-1234

or similarly you might put in a link

//work around stolen from this stackoverflow answer http://stackoverflow....

But not for the reasons you state of increased coupling. In fact I do name all my feature branches after the ticket they are for. So it is possible to trace all work back to a ticket if required, though the commit history. (also you can do some clever auto close stuff if you are feeling clever)

No, I am not worried about changing ticketing system. But what I have come to realise is that is super rare for anyone to look back at tickets once they are done.

So the comment is useful because it says to your future replacement:

"No i have not made a mistake, someone told me it had to be this way. Look! here is the ticket number to prove it!"

But they wont go and check that ticket. Life is too short.

If you get into a habit of putting ticket reference comments everywhere, then they lose their impact. Instead of being a flag "read this it is super important!" they just become clutter.

Generally requirements should be recorded through the medium of tests. If the tests passed, then the requirements must be met, we don't have to worry about how they were originally stated.

Answer 2

For Code Comments, there is very little usefulness. For version control comments, they are very useful for reasons outlined below.

Code comments really should be used to help understand the intent of complicated things.

Bad types of code comments:

• Updated EHS 10/24/2015 -- if I wanted to know that, I would use version control to find who wrote which lines.
• For spec 0.4 -- that can be part of the commit comments, but it doesn't help me understand the code any better
• Other variations of the same type of thing.

If code comments exist, they should help understand how the code block relates to the business domain.

---

If JIRA and your version control are linked then yes they make sense for Commit messages.

• Referencing the ticket provides traceability for the changes required to the work requested
• JIRA is not the only ticket tracking tool capable of this synchronization.

I do highly recommend a comment format something like the following:

 DIGIT-827: We only need to use the following for V4 of the computation.

JIRA and just about any tool with this integration is smart enough to recognize the ticket number and associate it with the ticket being resolved. That means a full URL is not required. It also means that you can get the benefits and provide meaningful comments for the particular commit all in one line.

When viewing the ticket in JIRA, you will see the list of changes with all the comments in context with the description, etc.

Answer 3

Yes, but only in rare cases.

Generally I imagine most of the code will be written in connection to a JIRA ticket, so I wouldn't routinely comment it with the ticket id - that's what git blame is for. But in some cases the code might be counterintutive - perhaps the most obvious way to write the code doesn't work and there was some discussion about why not on the ticket. In that case I would consider adding a comment with the ticket reference.

If one part of the code needs to work-around a known bug in another part then I would also consider adding a ticket reference.

I don't think this binds you too tightly to JIRA, as if you do want to migrate from JIRA to an alternative system you can export your JIRA issues as CSV and import them into the other system. The issue ID might change during that process but you should be able to preserve the JIRA ticket ID somewhere on the imported tickets.

Answer 4

It's certainly not a terrible practice to include JIRA issues in code comments, but this technique tightly/manually couples two disparate concerns (issues and code), and can require updates to multiple systems/locations (JIRA, anywhere in source the issue is mentioned, version control history).

Code comments are problematic in general because they are often not updated.

A better approach would be find some way to integrate your issue tracking system with your version control system, so that the two concerns can be maintained separately, in an automated fashion.

Answer 5

Put Jira issues in the commit comments, then use a plugin to link the commits to the actual Jira.
Our commit messages start with:

JIRA: XBVS-1222 Fixes bugs...

For example, then hooks between bitbucket and jira link the commits to the jira. Then it's easy to see which Jira it relates to in eclipse for example, by right clicking on the row number and selecting "Show revision history" I think it's called that anyway. Your Jira issue number and comments will be highlighted on the row number column, and hovering with the mouse will give you the details.

Answer 6

JIRA it's only a tool to track and organize your work.

Imagine if you need to change it.

What will you need all those issues codes for?

Will you clean up all the issues code by removing them?

Comments are used to explain what the code does, and often they too don't reflect this because they code change over time.

Example:

You comment this because the issue need an incremental counter. But after a revision you need a backwards counter for some reasons. Now this comment it's wrong

// DIGIT-123: The user need an incremental counter
count = 10
while count > 0:
  print(count)
  count = count - 1

---

I'm just adding food for thought, because each case has a different solution.