8

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.
  • rather blatant duplicate of Is it good practice to comment with issue number? – gnat Feb 14 '18 at 18:18
  • 2
    @gnat It wasn't "blatant", but thanks for the reference. – Mr_Spock Feb 14 '18 at 18:34
  • 1
    one small advantage is that tools such as IDEs can easily create hyperlinks to the corresponding ticket. – axd Feb 18 '18 at 19:17
7

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.

  • 1
    I agree. There are times I've searched the tracking database backwards but not often. I prefer having the relevant information in the code comments just so it's in one place, so I don't favor putting ticket numbers for worked tickets. On the other hand, I have gotten in the habit of leaving upcoming/future ticket numbers on TODOs that I might be leaving in the current code as it gives an idea when the TODO will get resolved, and if someone comes along later and finds the TODO for a ticket that's already closed, it's a flag that it got missed when the future ticket got worked. – jia103 Feb 15 '18 at 2:44
4

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.

  • Regarding the initials/date/description-of-change comment, while I agree that looking up in the repo is better, I want to point out that on my last project they concluded that our standard file headers with the initial copyright year combined with a running software history in the file header was sufficient evidence to keep the copyright current, so if a source file began in 2013 and it's being updated through today (2018), then the habit of updating the file header let the copyright continue with no added work, minimizing the chance of a lapse. – jia103 Feb 15 '18 at 2:52
  • @jia103, Copyright headers are a different matter than commenting a line was changed on such and such a date using someone's initials who may or may not be part of the team at the moment. One is a legal thing, the other is simple redundant information that provides no context to understanding the code next to it. – Berin Loritsch Feb 15 '18 at 14:32
2

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.

1

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.

  • 1
    Single Jira issue equals single branch and each commit is annotated with the Jira identifier for a specific issue, just like you recommend. I have used this for a long time and using git blame it is a great way to track code changes and their reasons without polluting the actual code with useless comments. – Andy Feb 14 '18 at 19:11
1

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.

Your Answer

By clicking "Post Your Answer", you acknowledge that you have read our updated terms of service, privacy policy and cookie policy, and that your continued use of the website is subject to these policies.

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