When I’m conducting a review, I hope the developer whose code I’m reviewing will see it as a learning opportunity. Some managers see code reviews as a time to catch employees making mistakes or inspire rank-and-file compliance with a giant checklist.

While I do have a checklist and some core things I look for in every code review, I’m much more interested in helping my developers understand the reasons why we write code the way we do, not just because the checklist says so.

With that in mind, in this post I’ll present a few guiding principles that I think about while conducting a code review. These aren’t the nitty gritty details but rather the high level concepts that make up good code, no matter the context.

Do I Understand What’s Happening?

This is the first question to ask with any code review, and answering it can reveal a lot about the developer’s thought process.

To begin, I want to understand what each part of the code is doing. Good code should be readable, and any savvy, experienced developer will write clean code that’s easy to understand what each part does. However, understanding the code is not a given. For complex problems or code that a less-experienced developer has written, figuring out what’s going on can be more challenging.

If it’s difficult to understand, that’s a red flag for me. It usually means the developer hasn’t thought about the solution well enough, and as a result they created messy code. Confusing code signals that there’s a simpler way to solve the problem.

Do I Understand Why It’s Happening?

Understanding what’s happening is only part of the problem. The other component is “Why does this need to happen?” This gets deeper into the developer’s thought process. It’s the part of the code review where I consider if a piece of code is really necessary in order to solve the problem. In many cases, the same functionality can be achieved with less code.

This is the kind of abstract problem solving that a code review checklist can’t encapsulate, but it’s among the most important parts of a good code review.

Is It Architected Correctly, Well-Formatted, and Commented?

Architecture, formatting, and commenting go hand in hand with the questions above, “What’s happening and why?” Code that’s organized and well documented is simply easier to understand. More importantly, however, it’s an indicator that the developer has thought clearly about the problem at hand and the best way to approach it.

One mistake I often see, especially from young developers, is code comments that explain what is happening instead of why it’s happening. Any good developer can read the code and understand what’s going on (as long as the methods, classes, and variables are well-named). The comments should explain why this piece of code needs to exist in the first place.

Is There Duplicate Code Anywhere?

This is another easy thing for me to check very quickly. The most obvious instance of duplicate code is copy-paste code that’s used more than once. The do not repeat yourself principle is a key to good code. Most developers inherently understand the benefits of reusable services, functions, and components and generic functions and classes.

How Easy Would it Be to Debug or Unit Test This?

When working under test-driven development, the tests should already be written. However, occasionally code hides or adds too many dependencies or has problems with initializing objects. The key here is constantly thinking about the tests you’ll write for this code and whether you can easily find and resolve problems.

Are Inputs and Third-Party Utilities Checked and Encoded?

The final guiding principle I follow in my code reviews is security-mindedness. Any time the application accepts an outside input, I want to make sure the proper security measures are in place so that the application isn’t compromised. Returning errors from third parties should be caught and invalid input parameters need to be handled properly.

Conclusion

Over the course of my career in software development, I’ve gone from junior developer to Director of Software. At first, my code was under the scrutiny of my managers and more senior developers. I made mistakes. I learned from them, and I write better code because of it. Those early code reviews were how the companies I worked for showed me what they expected in terms of code quality, formatting, documentation, test writing, and simplicity. Now that I’m the one conducting code reviews, I’m still learning every day. Hopefully, my code reviews can help the developers I’m reviewing improve their craft.