Skip to main content

The importance of code review - Four eyes see more than two

· 6 min read
Alexander Unterrainer
DefconQ, KDB/Q Developer, Consultant

Over the weekend, I performed an update on the version of Docusaurus, the documentation framework utilized for my blog. A major update had been released some time ago, and due to my limited enthusiasm for front-end development, I had been postponing this task as long as possible. However, I finally decided to tackle it this weekend. After reviewing the recommended upgrade instructions provided in the official documentation, I prepared all necessary steps and then started the upgrade. Incrementally I went through all steps, running my blog locally on my laptop, ensuring that I wouldn't break anything. After completing the upgrade, I conducted one final verification to confirm that everything was running as expected in my browser. Satisfied with the results, I committed my changes and pushed them to the repository of my blog.

Now, all that remained was deploying the new version to Github Pages. I executed the command USE_SSH=true yarn deploy as I typically do, pressed enter, and awaited the customary [INFO] messages. However, instead of the expected outcome, I was confronted with a bright, red error message.

[ERROR] Deployment of the build output failed.

Error: Running "git push" command failed.
Does the GitHub user account you are using have push access to the repository?

Ugh, of course. Something went wrong. However, my blog ran smoothly locally. I meticulously reviewed all my steps again, compared the docusaurus.config.js file with the new docusaurus.config.ts script I had to generate as part of the transition from JavaScript to TypeScript. Everything appeared to be in order. So why wasn't it functioning properly? The error message resembled an SSH issue, prompting me to double-check all my GIT configurations, and even recreate SSH keys, but to nothing.

Then, I proceeded with the typical routine every developer follows when encountering an issue: I searched for help on the internet, StackOverflow, Google search, blogs, forums, but unfortunately, none of the resources I explored offered a solution to my dilemma. Eventually, I stumbled upon a post suggesting that I delete the gh-pages branch of my repository — the branch responsible for hosting my blog online - and recreating it might resolve the issue. This sounded like a plausible remedy, so I proceeded accordingly. Regrettably, the solution did not rectify my problem; in fact, it exacerbated it. Deleting the branch responsible for hosting my blog rendered it inaccessible. While I may not boast millions of readers, the embarrassment of visitors encountering an offline blog was real.

I began to feel a tinge of concern and proceeded to review everything one more time, attempting a few additional troubleshooting steps, but nothing worked. At this point, my last resort was seeking assistance from a more seasoned developer. Fortunately, one of my close friends from university happened to be one of those exceptional talents - often referred to as 10X developers in the tech industry. Regardless of the topic at hand, he possessed the ability to grasp concepts within minutes. Most technical challenges that had stumped me in the past seemed trivial to him. While the only programming language he wasn't well-versed in happened to be KDB/Q, I was fortunate that this particular issue did not pertain to that domain. Armed with a few screenshots and a concise explanation detailing my efforts and attempted solutions, I composed a message and eagerly awaited his response.

Knowing that he had recently welcomed his second child and that my trivial web development issues were understandably not a priority compared to his new responsibilities, I decided to take a leisurely stroll with my girlfriend and some friends. Several hours later, I received a response from him—a few links to potential solutions, all of which I had already explored. Following that, he inquired about my GIT repository URL, username, and a few other details. After confirming these details, I received a smiley face emoji in response. It was then pointed out to me that I had a typo in my GIT username—I had mistakenly written DecfonQ rather than DefconQ. With this embarrassing oversight corrected, I was finally able to deploy my blog once again, and it was back up and running as usual.

This experience, reminded me once again, about the significance of code review and why it should be an integral part of every software development life cycle. Which brings me to the main topic of this blog post: code review.

What is code review and why you should practice it

In the software development industry, code review is a fundamental practice that involves systematically examining code changes made by developers. It serves as a crucial quality assurance measure, ensuring that code meets standards, is free of bugs, and aligns with project requirements. Code review is important for several reasons:

  • Firstly, it provides an opportunity for developers to have their code reviewed by their peers ensuring certain quality standards and controls, receiving valuable feedback on potential improvements or adherence to best practices.
  • Sharing and transferring knowledge: Code reviews are a great opportunity to share or gain expertise. The depth of this knowledge transfer varies widely, however, there will always be some level of information exchange.
  • Spreading ownership: Code reviews allow developers to review code written by others, facilitating learning and deeper understanding of the system being developed. This will foster mutual code ownership. It's common for a developer to become solely responsible for a specific part of the codebase due to their familiarity with it. While this might offer short-term advantages, it often leads to long-term drawbacks. When ownership of the code is shared among team members, it promotes motivation and autonomy within the team.
  • Moreover, code review encourages collaboration within teams, as developers can provide constructive feedback to one another and engage in discussions about software development practices.
  • Unify development styles: Each developer has their unique approaches and preferences when it comes to implementing software. Code reviews play a crucial role in bridging the gap between individual development styles, thereby promoting a more unified codebase. This unification occurs through both high-level discussions concerning architecture and software design, as well as micro-level continuous integration checks like enforcing coding style consistency.
  • For junior developers, code review offers a unique chance to benefit from the experience and expertise of more seasoned developers.

For a comprehensive guide on code reviews and best practices, make sure to read the excellent article "A Complete Guide to Code Review" by Kimmo Brunfeldt.

Ultimately, no code should be deployed to a production environment without undergoing a formal code review and obtaining the approval of at least two other developers, a best practice that development teams should adhere to. DefconQ on the other hand, will simply postpone future front end updates or outsource it to an experts. Volunteers are more than welcome.

Resources: A complete guide to code reviews by Kimmo Brunfeldt