In this story, we would like to talk about one of the steps in software development, which is called review.  

In brief, review is the process when someone checks others’ outputs. It can be done in many ways, even while working in pairs, but it mainly depends on what tools the company is using.  

Intentionally we do not call it “code review”, which you might think is the correct nomenclature in terms of software. The reason is while coding is a core of software development, there are plenty of other areas that need to be covered like tests or specifications.   

The review process may touch them all – when people are writing test plans or documentation, there is a moment when someone needs to check it, specifically for critical areas, or when the author just started working in this space.

When and what to review?  

As we talked about in one of our previous stories (https://rsoftcon.com/blog/how-processes-in-organizations-may-influence-productivity), how you are going to shape your software development has a huge impact on your productivity. One of the important aspects that your company needs to consider is a review. Depending on your software or company structure or other reasons, you might have different areas under review process:  

• Code (production code, environment code, unit tests code, etc.)  
• Tests (test plans, integration tests, manual testing, etc.)  
• Documentation (architecture documents, APIs, developer’s environment setup etc.)  
• Specification (use cases, user stories, requirements, acceptance criteria, etc.)  
• And more…  

As you may notice, the review process can be established at any point in time. However, it does not mean it should be.  

Review is quite a heavy process – it requires at least one person, who stops his current work (unless it is a dedicated person for review which is quite uncommon) and starts checking someone else output. Depending on the quality and complexity of a document it might take from one minute to a couple of hours.  

How to decide, when to introduce a review and what could be the scope of it will be a part of one of our next stories. In this paragraph, we just wanted to highlight that such a decision has a big impact on your productivity.  

Types of reviewers  

The review process requires formalization on two sides – how to prepare a code or document for a review (formalization of minimal requirements) and who shall review such code or document (dedicated person, randomly chosen from a group, etc.).  

After this “short” introduction we want to focus today on this second aspect.  

First, let’s talk about relations between a project and reviewers. If your project is small and not complicated, managed by one agile team (e.g. 10 people), then probably reviewers are just randomly chosen based on the availability of other team members. In most cases, it is not a problem – the whole team knows the project, and anyone can give proper feedback. What is more, even if some bug won’t be caught on the review, the fix is quick and cheap (as mentioned, considering the small complexity of a project). In such cases, the review process is also relatively cheap, as people find rather only obvious issues, so the time spent on the code or document is short.  

When the complexity or size of a project grows, then every missed bug in the review process starts to be a bigger problem. It is not only about the cost of correction (creating new test cases, possible specifications, etc.), but also about the risk of introducing a new bug. In very complex projects it can be a nightmare – people introduce bugs, try to fix them, but then introduce them more. In such cases, the review process needs to be considered as very important and reviewers need to be properly chosen.  

As we mentioned before, a review process might be established for plenty of different areas. It can be code, documentation, or tests. However, even if these areas have different outputs, we can try to find common attributes of them.  

The first attribute is the quality of the document. It means that a document (which can be also a code) follows formalized rules. For example:  

• Architecture follows the C4 model.  
• Specification of flow is written in PlantUML.  
• Production code contains tests.  
• Tests are written in a defined framework.  
• Tests are using mocks, not stubs.  
• And more…  

You may notice that such rules are very different – it depends on the type of document (code, specification etc.), but also, they can be defined specifically for a project or company. Every project or company may follow different rules, but all rules are defined and formalized.  

The quality of the document is separate from the correctness of the document. In other words, if a document follows some predefined rule, it does not mean that it is correct. Let’s take an example of the code – it can be written with the highest quality:  

• Correctly named parameters.  
• Usage of abstraction or inheritance.  
• No whitespaces.  
• No code duplication.  
• And so on.  

However, the same code can be wrong:  

• It is not sending messages to component A.  
• It does not handle messages from component B.  
• It generates one table, while the requirements are to show many tables.  

This is why we can define the first type of reviewer – a person who has a lot of knowledge about rules. In terms of the code, it will be a person who has worked with this code language for many years and is an expert in this field. For specification, it will be a person who knows what specification needs included and what can’t to avoid misunderstanding from developers (it is called “boundaries of specification”, we will describe it in our next stories).  

It is important to mention that such a person does not necessarily belong to a project if rules are set up for the whole company. Even if documents are from different areas, then the quality of documents needs to be the same and this is what such a person will check.  

As already mentioned, the second attribute is the correctness of the document. Here we talk about a good knowledge regarding the project. This requires a different view – does the document fulfill expectations? Does the document follow requirements? Does code is in line with architecture?  

This type of reviewer does not need to be an expert in code language or even does not need to know any mentioned quality rules. While it is desirable anyway, it is perfectly fine to have only deep knowledge about the project itself to properly analyze outputs generated by other team members.  

Summary  

Review is an important part of software development because it can be cheaper to find a bug by reviewing a document instead of fixing it. On the other hand, the review process needs to be correctly defined to get the highest “return on investment”.  

One such aspect is to establish who shall review what. Wrong decisions here may result in a useless review, which wastes the time of the reviewer and the person who makes corrections.  

In complex projects, it is desirable to find two types of reviewers – quality guard and knowledge guard, which together will cover the review of documents in two dimensions – the document’s quality and correctness of the document.  

How to find such people, how to establish a review process, or where to start – we in RSC can help you in these areas.