A Framework for Code Reviews
Tags: codereview, bestpractices, cleancode
Published: 2018-11-22 03:41:41

---
title: A Framework for Code Reviews
published: true
description: A description of a framework for code reviews that borrows from the practice of forensics. 
tags: code review, best practices, cleancode
---

I believe that good software is not only performant- it is also easily readable by human beings. 

Therefore, writing software that is easily parsed by other people requires showing other people my code and asking them what they think. And as a professional front-end developer, such code reviews are integral part of my work. 

In this post, I will describe the framework that I use for thinking about professional code reviews. 

It's called the PCAN method, and it's something that I picked up during my time as the coach of the world's number one ranked inter-collegiate parliamentary debate team. 

It's an acronym which stands for:

-Problem - What is the problem which needs to be dealt with? What impact is it having on operations?

-Cause - How did the issue arise? Is it due to human error than can be prevented in the future?
 
-Answer - What is your answer to the problem? What assumptions does your answer rely on?  

-Net Benefit.  - Describe the net benefit of your answer. What are its pros and cons? 

Like all frameworks, the PCAN method is not a one-size-fits-all solution or a replacement for thinking about code reviews in the context in which you encounter them at work. But I think that there are elements of this framework that most people can apply to the way they approach code reviews and see immediate benefits. 

## PCAN In-Depth

###Problem - What is the problem which needs to be dealt with? What impact is it having on operations?

Knowing why a change to the codebase needs to happen is the most important piece of context that the person reviewing my code needs in order to evaluate my work. 

If I'm lucky, this information will be provided by the person who flagged the issue originally. 

But more likely than not, I'll have to do some further exploration to identify what the issue is

###Cause - How did the issue arise? Is it due to human error than can be prevented in the future?

My boss is a big fan of the DRY principle. Therefore, whenever I'm dealing with an issue, I try to keep an eye out for any aspect of the work that can be automated or made more reliable for future users. 

This involves a deeper level of understanding- rather than just knowing what the problem is, I try to figure out why it happened. 

Did the previous coder model the domain incorrectly? Perhaps there are structural weaknesses in the codebase of which the problem is only a symptom. 

Understanding the cause of a problem helps me to write code which is more productive since it addresses not only the issue at hand, but a whole class of similar issues.

Example:

Since I'm a front-end developer, I use the Chrome Inspector a lot when debugging performance issues on the sites I maintain. I also use the React Profiler, since the main application I work on is built using React.js. Of course, I make copious use of `console.log()` statements in my code editor to figure out what is going on.

Recently, I addressed an issue where my the drop-down effect on my site's mobile nav menu wasn't working as expected. It seemed like an issue with the JavaScript code, since that's what controlled the state of the menu. 

But after further investigation, I realized that the issue was with the CSS classes which were being applied to the that section of the code. Rather than spending a lot of time messing with the site's pretty complicated JavaScript, I was able to make a few CSS edits which got the job done.

###Answer - What is your answer to the problem? What assumptions does your answer rely on? 

This step is where I lean on my knowledge of data structures and algorithms to devise elegant solutions to the problems I am faced. 

I'm lucky that the programming language that I use the most, JavaScript, has features which make it more readable for humans than other languages. 

I take advantage of functions like `.map()` and `.filter()` to make the order in which I am transforming data clear. I use clear variable names and regular indenting patterns to make clear the relationships between different parts of my code.

-Net Benefit.  - Describe the net benefit of your answer. What are its pros and cons? 

This step is where I justify the time and money expense behind my efforts. As a professional software developer, I have to be accountable for my time and also cognizant of the need of the organization to grow. Pushing code which addresses major bugs and adds performance features is the core of that work, which makes documenting the rationale behind any changes I make to the existing codebase an important part of the process. 

## How Can PCAN Help You?

A good code review process will encourage the following behaviours at a software company:

- collaboration among colleagues working on related projects
- reinforcement of the organization's HR management philosophy
- documentation of key software architecture decisions

These can all become key drivers of a software organization's competitive advantage if there is a clear process which encourages transparency and openness. 

By implementing the PCAN processes for your code reviews, I think you will be one step closer towards being a great developer. 

Let me know what you think!