Hacker News Reader

Comment by ajuc | Hacker News Reader

Requirements should be in the JIRA. JIRA number should be in the commit message.

You do git blame and you see why each line is what it is.

Comments are nice too, but they tend to lie the older they are. Git blame never lies.

A code tends to be reused. When it happens jira is not likely to travel alongside the code. All 'older' jira tickets are useless broken links. All you have in practice is jira name. It usually happen with 'internal documentation' links as well.

Git blame often lies when big merge was squashed. I mostly had these in Perforce so I might be wrong. Also when code travels between source version control servers and different source version control software it also loses information.

I would say in my gamedev practical experience the best comments I saw are TODO implement me and (unit) test code that still runs. First clearly states that you have reached outside of what was planned before and 2nd allows you to inspect what code meant to do.

One of my favorite conventions is ‘TODO(username): some comment’. This lets attribution survive merges and commits and lets you search for all of someone’s comments using a grep.

I tend to do:

  // TODO: <the name of some ticket>: <what needs to happen here>

e.g.

  // TODO: IOS-42: Vogon construction fleet will need names to be added to this poetry reading room struct

I've not felt my name is all that important for a TODO, as the ticket itself may be taken up by someone else… AFAICT they never have been, but they could have been.

Jira entries get wiped arbitrarily. Git blame may not lie, but it doesn't survive larger organizational "refactoring" around team or company mergers. Or refactoring code out into separate project/library. Hell, often enough it doesn't survive commits that rename bunch of files and move other stuff around.

Reply on news.ycombinator.com