Engineering practice: git, code, tests · Chapter 3 of 12 · Craft · new chapter every Sunday night

By the end of this chapter: Review effectively and receive review without defensiveness.

The problem

You are a junior engineer on a two-week sprint for the payments team. Mid-sprint, you discover a flaky test that fails on the CI runner every night. You open a branch, add a one-line guard clause, and push. The CI pipeline passes, so you think you're done and type:

git commit -am "fix bug" git push origin payment-guard-2024-09-15 

However, when you submit your pull request, a senior engineer reviews it and points out that your commit message doesn't follow the team's conventions, and your code change, although correct, doesn't include any tests to verify the fix. The reviewer also mentions that the code could be improved for readability and maintainability. You feel defensive about your code and wonder why the reviewer is being so picky. You start to question whether you're cut out for this job.

The problem is not just about the code change, but about how you receive and respond to feedback. You need to learn how to review code effectively, both as the author and as the reviewer, and understand what to look for in a code review. This will help you improve the quality of your code, learn from others, and become a better engineer.

Before you start

To follow along with this chapter, you should have completed the previous chapters on Git as a thinking tool and branching, rebasing, and conflicts without fear. You should be comfortable with Git basics, including committing, pushing, and pulling changes. You should also have a GitHub account and be familiar with the GitHub interface.

To verify that you have the necessary setup, run the following command:

git --version 

This should output the version of Git installed on your system. If you don't have Git installed, you can download it from the official Git website.

What to look for in a code review

When reviewing code, there are several things to look for, in a specific order. First, you should check that the code is functional and correct. This includes verifying that the code fixes the intended bug or implements the desired feature. Next, you should look at the code's readability and maintainability. This includes checking for clear and concise variable names, proper commenting, and a consistent coding style.

You should also check for tests. Are there any tests that verify the code change? Are the tests comprehensive and cover all the possible scenarios? Finally, you should look for any potential performance or security issues.

How to give and receive feedback

When giving feedback, it's essential to be specific, clear, and constructive. Instead of saying "this code is bad," say "this variable name is unclear, consider renaming it to something more descriptive." When receiving feedback, try not to take it personally and focus on the specific points being made. Ask questions if you're unsure about something, and be open to changing your code.

Build it

Let's go through an example of how to review a code change. Suppose you're reviewing a pull request that adds a new feature to your team's project. The code change includes a new function that implements the feature, but it doesn't include any tests.

Here are the steps to follow:

  1. Check the commit message: Is the commit message clear and descriptive? Does it follow the team's conventions?
  2. Verify the code change: Does the code change implement the desired feature? Are there any obvious bugs or issues?
  3. Check for tests: Are there any tests that verify the code change? Are the tests comprehensive and cover all the possible scenarios?
  4. Review the code's readability and maintainability: Are the variable names clear and concise? Is the code well-commented and easy to understand?
  5. Check for performance and security issues: Are there any potential performance or security issues with the code change?

When this breaks

There are several ways that a code review can go wrong. Here are a few examples:

  • The reviewer is too harsh: The reviewer is overly critical and focuses on minor issues, rather than the overall quality of the code.
  • The author is too defensive: The author takes the feedback personally and becomes defensive, rather than focusing on the specific points being made.
  • The code change is too complex: The code change is too large or complex, making it difficult to review and understand.

In each of these cases, the key is to stay focused on the specific issues and avoid taking things personally. As the reviewer, try to be clear and constructive in your feedback. As the author, try to be open to feedback and willing to make changes.

What it costs

Code review is not free. It takes time and effort to review code thoroughly, and it can be frustrating to receive feedback on your work. However, the benefits of code review far outweigh the costs. By reviewing code regularly, you can catch bugs and issues early, improve the quality of your code, and learn from others.

In terms of specific costs, code review can take up to 30% of a team's time, depending on the size and complexity of the codebase. However, this investment can pay off in the long run by reducing the number of bugs and issues that make it to production.

In the interview

In an interview, you may be asked to review a code sample or explain how you approach code review. Here's an example of how you might answer:

Interviewer: "Can you walk me through your process for reviewing code?"

You: "Yes, definitely. When I review code, I first check the commit message to make sure it's clear and descriptive. Then, I verify the code change to make sure it implements the desired feature. Next, I check for tests to make sure the code change is verified. Finally, I review the code's readability and maintainability to make sure it's easy to understand and maintain."

Interviewer: "That's great. Can you give me an example of a time when you received feedback on your code and how you responded to it?"

You: "Yes, definitely. One time, I received feedback on a code change I made, and the reviewer pointed out that my variable names were unclear. I took the feedback and renamed the variables to make them more descriptive. I also added comments to explain what the code was doing."

Your tasks

  1. Review a code sample: Find a code sample online or in a project you're working on, and review it using the steps outlined above.
  2. Give and receive feedback: Find a partner or colleague and exchange code samples. Give each other feedback and discuss the feedback you receive.
  3. Implement a code review process: If you're working on a team, implement a code review process that includes regular reviews and feedback. If you're working alone, find a way to get feedback on your code, such as by joining an online community or finding a mentor.

By following these tasks and practicing code review regularly, you can improve the quality of your code and become a better engineer.

Your tasks this week

Do the exercises above before the next chapter. Reading a tutorial and doing
one are different activities and only one of them changes what you can build.

Stuck on any of them? Say so — describe what you tried and what happened:
tell me where you got stuck. I read every one, and the questions
that come back more than twice get answered in the next chapter.

Engineering practice: git, code, tests

Chapter 3 of 12. New chapter every Sunday night.
Next: Naming, the hard part.

· The full syllabus and every chapter so far
· Subscribers also get the condensed notes for this chapter, the running
recap of everything the series has covered, and the extended guidance:
subscribe

Written by Amit Chakraborty — founding engineer and senior architect: React Native, AI and RAG systems, production architecture. Portfolio · LinkedIn · GitHub.

Need this built, reviewed or taught to your team? Get in touch or email amit@devamit.co.in. Available for senior and founding engineering roles, consulting and training, remote worldwide.