[ampersandy]

I don't really buy the two main criticisms around code review. They're stated as intractable downsides but are really just cultural issues around how you perform code reviews.

If your coworkers are sending changes for review that don't explain why the changes are being made (and therefore provide the context), reject it until they write a proper summary/test plan that does explain it. You should review the "metadata" of changes before you ever review the code itself and if done well, you'll probably be able to guess what a lot of the incoming changes are before reviewing the code. This makes it easier to spot code that deviates from the stated purpose of the changes and can help identify faults in both understanding of the overall problem or the system being built, especially in more junior engineers.

If your coworkers are taking to long to review changes, work with your team to incentivize expedient code reviews, or talk to the people that aren't reviewing enough code to help everyone else get more done. You should also utilize a stack that lets you continue progressing with your work even when waiting for reviews (like stacked diffs).

[plorkyeran]

The first criticism ("Context Gaps. The reviewer doesn’t have the full context of how and why decisions were made for the code they were reviewing.") is one of the things I consider a _advantage_ of code reviews. The article just dismisses the idea that having the reasons for decisions written down is useful, which I find extremely strange.

[rekahrv]

'You should review the "metadata" of changes before you ever review the code itself'

That's a great approach. It sounds logical, but I certainly don't do it consistently. :-)

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