[watwut]

The context is not just "why the change was made". That point is usually clear from ticket in the first place. The context is "do other places in code use the same tactic" question. It is also the "I tried these four things and three of them failed because of X" or "I had to choose between these two solutions and picked this one".

[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.

[onion2k]

Do those things matter once the code is actually written though? They're important during the dev process, particularly if you're deciding between two different-but-valid approaches, which is why teams should be communicating and discussing things, but once the decision has been made it ceases to be anything worth worrying about. It's a sunk cost. It shouldn't need to be a part of a code review unless the comms are failing ahead of the review process. If that's the case then you should try to fix the comms issue.

[taeric]

A lot of what we devs think are vitally important... just aren't. Or, they have a steep time decay on how useful they are.

I do have the longest code review summaries on my team, amusingly. So, I clearly like the idea of it being a discussion and capturing some of that. I would be challenged to say what part is most important overall, though. In large, because not all code changes are the same.

[rekahrv]

"Do those things matter once the code is actually written though?"

That's a great question. I guess it depends on how much the code will change in the future. These things CAN get relevant again when you consider changing that code. E.g. if it turns out later that the library I've chosen isn't maintained anymore. Or we would need some more functionality, but this library doesn't provide it. In these situations, it's useful to see which other alternatives we've considered.

That said: I can't really estimate how often this turns out to be relevant, indeed. I guess the answer might be very different for different projects.

[watwut]

I think it does not make sense to write them down as comments or in the pull request or anywhere else. It makes sense to talk about them during review process where reviewer might have different opinion - or might think the other option is better because reviewer does not know about the issue.

[arp242]

This is the kind of stuff I would add in the commit message (and PR description): "I ended up choosing solution A because B, I also tried C and D, but that didn't work so well because E".

Everything you say that's not written down will be lost in the aether within weeks, months at best. I'm a huge fan of async communication because everything will be written down.

If there's a discussion "why did you go with A and not B", in an (async) code review then anyone can come back to it a year later and read up on why it was done in this particular way. I've found this useful on a number of occasions.

It certainly beats "Alice, you changed this last year, but why is it done like that? Wouldn't X be much more convenient because Y? It's hard to add Z now.", "ehm, I discussed it with Bob, but he since left the company. I don't quite remember, I think it was A? Or maybe B? Or was it C?"

[MajimasEyepatch]

Generally, those are all good things to include in the commit message.

[watwut]

I dont think so. The "do other places in code use the same tactic" especially not. This is something ideal reviewer would check, consistency is important. But it does not make sense to write it anywhere.