[ajorgensen]

Having the “why” in the same place as the code I think is critically important. Who knows what ticketing system you’ll use in the future, it’s fine to link to but it shouldn’t be where all the context is stored.

If you think about a pull request as a story you have who, what, where, when, and why. Most tools handle the first 4 but the why is critically important to anyone, including yourself, who needs to understand the nuance of the change that can’t easily be expressed by the code itself without a novel size comment block.

I find that a lot of times people forget the “why” when submitting a change set and simply restate the “what”. At the time you make the change it’s all fresh in your mind and you trick yourself into believing you’ll remember all the details but in reality that’s no my experience.