Why do people bend over backwards to complicate simple logic and architecture?
A developer complaining about code reviews
Reviewing code can be painful. We set aside our work, switch into someone else’s context, and then put time into providing useful feedback. It’s frustrating when other developers reject our simple suggestions and fight to justify their complex solutions.
Let’s consider common reasons that code reviews can feel like a fight, along with some options for making the process flow more smoothly.
Reason #1: The code works
Sometimes, developers are only looking for verification that the code works as expected. In this case, any suggestions we give about style or different options aren’t likely to be received with enthusiasm.
If the code works but could be improved, consider accepting the code while also providing some non-blocking improvement suggestions. Being explicit about style review versus verification review can help set the proper environment for suggestions.
If the code is so complicated that we can’t verify it works, we should make that clear. “I’m not sure if this works because of X. If you instead did Y, it would be easier for me to verify the code works.”
Reason #2: The code exists
Any code we’re reviewing has a distinct advantage over our suggestions: it’s already written. And code, once written, is not easily thrown away.
An alternative approach to code review, as it’s normally practiced, is design review. Designs are less concrete than code and often more amenable to change. Once we get agreement on a design, code review is verification that the code meets the design rather than doing double duty of design review and verification review.
Reason #3: We’re missing context
When we step into a code review, we’re always missing context. The suggestions that seem simple to us might have already been considered and rejected. We should practice asking questions to determine if there are reasons our simple suggestion isn’t appropriate.
We can also explicitly state tradeoffs with our suggestions. Doing so will force us to recognize that there is possible context that would render our suggestion invalid and communicate to others that we’re not overly attached to our own ideas.
Reason #4: The value isn’t clear
What feels obvious to us isn’t obvious to everyone. We should be prepared to explain why our suggestions are an improvement. If we’re unable (or unwilling) to do that, we should accept that maybe our obvious solution is neither obvious nor a solution.
Reason #5: It doesn’t feel like collaboration
Code reviews are supposed to be helpful to everyone involved. We should learn from each other while building the best systems possible. We should be purposeful in ensuring our teammates know that we are personally invested in their success, as well as our own. If our suggestions come across as nitpicking, posturing, or showing off, we’ll continually be met with hostility. And rightly so.
Except for extreme cases, developers aren’t purposefully creating a spaghetti mess of code. If we acknowledge that, along with our own shortcomings, we’ll learn more from doing code reviews and find them much more productive.