New to the Project? Do Code Reviews!

Evgenii Ponomarev -

I put it straight – you do not need to have any prior knowledge about the codebase to start doing code reviews.

This article is going to be about why all new developers should review code, and how to get the most out of it. If you do not need any convincing or guidance, you may rather watch how I win a fight with my cat.

"New developers" in this context are not only people who have just started a career but also experienced developers working with the unfamiliar codebase.

Benefits of doing code reviews

First of all, it is going to speed up your onboarding. Right now, your learning is limited by the number of tasks you are directly involved in — you learn from your own successes and mistakes.

Reviewing other solutions is a quick way to get around this limit. You can get to know various parts of code without touching them personally and see what works and what does not for different types of problems.

On the other hand, your feedback will be beneficial to the team because you have a crucial trait that no one else has — fresh eyes with no prior context.
As writers cannot edit their own texts, programmers rarely can judge their code. We know too much about why it is written this way, and the more people share the same understanding, the harder it is to have an unbiased opinion. While you have limited knowledge, you are the only person who can give a fresh view and challenge what others take for granted.

How to approach code reviews

1. Do not be afraid

All teams I worked with had a high demand for code reviews, which is quite common in the industry. Therefore, do not be afraid of starting — nobody will mind having one more pair of eyes available.

It is quite common to fear not catching a bug or merging code that would need some improvements. A workaround is simple — do not approve a pull request if you are not sure. Leave your comments, ask questions, and ping somebody else for a final verdict.

2. Understand the problem

Before looking closely at the code, familiarize yourself with the problem:

  • What is the definition of done?
  • Is it complete?
  • Would you add anything else?
  • How would you test it?

Think about all possible use-cases the author may need to implement. Then, either remember them or write them down — this is going to be handy soon.

3. Draft your own solution

Remember, we are not reading code yet :-)

To get the most from this learning opportunity, think about how you would approach this task:

  • How to structure data?
  • Where to put logic?
  • Is there anything in the codebase you should reuse? If unknown, how would you search for it?
  • Who is more knowledgeable in this area to advise you if you were the one picking this task?

Once again, write it down or keep in your memory — up to you.

4. Prove that the problem is solved fully

Now it is the time to start looking at implementation but only at a high-level. Focus on what rather than how.

Sometimes, clear and correct code does a wrong job:

  • An author may misread or misinterpret requirements
  • They may implement some parts and forget the others

Look at the list of possible use-cases you prepared earlier:

  • Are all of them handled?
    If not, ask whether they need to be — it is safe to assume that you are the one who misunderstood the problem.
  • Are there any cases you did not consider?
    If the author implemented something you did not even think about, it is excellent — you already learned something new!

5. Compare your solution with the pull request.

Now you know how you would approach this problem, but how did the author solve it?

Find differences between both approaches and try to understand the pros and cons of each. The best way to do it is to ask questions:

  • Why was it preferred to put X and Y to the same database table, rather than keeping them separately?
  • Why was the primary logic put to module A, while module B has similar pieces that might be collocated?

This way is how you learn the most — not by reading the code and checking it for correctness, but by exercising your skills and validating proposed solutions.

6. Ask questions about code.

When you get the answers to all high-level questions, it is time to zoom in and look deeply at code:

  • Is it easy to understand or something needs further clarification?
    Questions from new developers often mean that the code is not as self-explanatory as it could be. The author may consider adding comments or restructuring obscure fragments.
  • Are there ways to improve the code?
    Even though you're new to the project, you can read and write code, right? Leave a suggestion when you see a room for improvement — after all, it can only help.

People frequently ask where is that line between giving useful comments and nitpicking. Is it appropriate to ask to rename a variable or to chase a negligible performance improvement?

As for me, everything is alright as soon as you communicate what is essential and what is not. I always prefix minor comments with the words 'minor' or 'nit', so the author knows which are ok to ignore.

Come back later

If the pull request was not immediately merged — make sure you check it for new comments later.

Someone may reject it despite your approval; someone may add fruitful comments — this is just another piece of context that is never superfluous.