Any programmer will tell you - WTFs per minute is a metric whose hilariousness is surpassed only by its truthiness.

Now, there’s one - rather obvious, I admit - lesson I learned in my programming career: when you inherit a codebase any information that can help you decrease the WTF count is priceless. Sure, documentation helps and so do tests. But when you actually open the code in your editor and dig deep into the lines, the essential question you ask is why does this code look the way it does? And sadly that’s a question neither documentation nor tests can really answer. Not with enough detail, no.

Yet, there’s one simple thing that can. And I promise you if you start doing it today, you will lead a happier life (or at least you’ll decrease the chance of being brutalized by the next maintainer). To top it up it’s really, really easy. Ready? Here it is:

Link every commit to the relevant issue in your issue tracker.

Bam! Not exactly an eye opener, right? Yet I’ve seen a disturbing number of projects doing it intermittently or not doing it at all. And this is one of the habits that brings most benefits when applied consistently.

It's as easy as writing Fixes #14 in your commit message.

It's in fact such a useful feature many issue trackers support this natively and will even hyperlink the issue number for you. In my previous company, Salsita, we wrote a tool to facilitate (a slightly modified version) of Gitflow and we made it mandatory to link each single commit to an issue.

Connecting changesets to tickets has two beneficial effects:

  1. You can git blame every line and jump to the relevant issue to see what feature was the change part of and - in most cases - find out why a strangely looking change was made the way it was (usually from a discussion linked to that issue).
  2. It helps prevent cowboy coding or refactoring just for refactoring sake which is just-so-easy for programmers to fall prey to (by forcing you stop to think which feature is your commit actually relevant to).

If there’s one project maintaining advice I would give to any programmer which would make her life easier, it is this one simple thing. It pays off handsomely in the long run.

Happy maintaining! I’m @tomas_brambora.