Code Review: a better way

January 27, 2020

I have been reviewing code for more than a decade. I tried many approaches for efficient code review. I remember the following

  • provide the better code on the line that needed an improvement
    This causes developers to make the same mistakes again. It took the shortest time but continuous mistakes took more time.
  • accept sub-optimal code and hoping for the better code next time
    This lowered the coding standard and worse, others copy and paste the code and get away with it: it was like this before. Those who end up changing may think it’s unfair for them.
  • Asking questions on the code
    Instead of, a statement “This is inefficient because …”
    Asking, “Is this efficient?” ended up having developers think about the code. It takes some time for developers to learn but it just lowered developers’ pride as the time pressure kicks in and gotta get it done. “I think so, please tell me what I can improve (or accept)!”
  • So many ways I tried. I even had arguments over language syntaxes and pointed at the language documentations. I felt as I was trying to tell a dog to see the moon as explained in this nice video.

A decade passed and I finally realized a better way to review code.

To criticize other’s code is to criticize a book. Your first goal is not to find an errata. Your first goal is to get the feeling of your fellow developer who wrote the code to solve a problem. In order to understand more, you would need to know what his plans were but first, you must know his coding level.

From that, you will read the code and it then shows characteristics of the code. That is, does the developer

  • fear (uncertainty of code behaviour) seen for code area new to the developer
  • confidence code written with expertise which can be blindingly wrong

Only after reading in their view and thoughts, you can then provide feedback from your view and thoughts. It’s not to remove the fear, but to guide them a better approach in their concerns.

Fear and confidence are emotions and there are many more. When you feel what others feel, you understand the code better and you can communicate better asking questions without condescending.

A few years ago, I read Clean Code which has

The only valid meansurement of code quality: WTFs/minutes

Clean Code by Richard C. Martin

Then, I thought it’s a norm to tell other developers what’s wrong and get it fixed. The same thing happens again. Unfortunately, not all developers want to improve.

Only humans are capable of empathy, and that to enjoy reading a book requires aligning your emotions to that of the author. Only then do you understand the writer’s intention and embrace or criticize effectively with your knowledge. It’s the learning experience for both parties.

Technical books will teach you how to code better. Practicing empathy will enhance your code review and help build strong teams.

Here are some tips you can practice

  • when you feel the fear, encourage exploration and clarify the use
  • when you feel the overconfidence (e.g. dictionary data expected in sorted order), kindly point a link to document that invalidates the assumption.

Know your peers and their skill levels and guide them, because that’s the role of a tech lead.

© 2023 Kee Nam