Digital businesses can live or die based on the quality of their software. While strategy, market fit, sales and marketing have crucial roles to play, ultimately if the software is defective customers or partners will leave. They are unlikely to return and the business will suffer.
BSP Software has extensive experience is helping companies fix these core issues through a Code Review process.
Over the next 7 posts we will explain the Code Review process in an effort to demonstrate the importance of allowing your business to succeed without deploying faulty code to your customers.
In Part 1) of Code Review we will outline the Author and Reviewer Preparation steps.
Code review process that works even in real-life environments
Peter Gabris, MD of BSP Software Inc
‘Bugs happen’
Software is written by mortals; mortals err. There are various categories and reasons of code defects ranging from typos through omissions going all the way to misleading documentation or even a wrong requirement.
The code review is one of many tools to help us rid the code of errors. While code reviews are labor intensive they are proven to be considerably more cost efficient than errors found in testing not to mention the cost of a bug in production software reported by a client.
There is more to code review benefits than the list of defects found. Many defects are found and fixed during the code preparation for the review. Code review provides an excellent learning experience for both the reviewer and the code author. The reviewed code is much better prepared for the maintenance and future expansion.
Code review is not a tool to judge programmers or reviewers. Hard code has more defects. Therefore, code review statistics are never linked to employee personal growth plans or to employee/team performance evaluations. However, serious bugs left in the code committed for the production deployment might be a free game.
Preparation for the code review
Author preparation
Code review is your rare opportunity to show off the code you are proud of. The better is the code the higher is the prospect that it will be diligently working for years without anybody ever seeing the smart way you did it.
Code review is not a substitute for professional, quality programming. The reviewer is not responsible for bugs left in the code. He/she will spend time and effort to help you and to add confidence that your work is up to standards and can be expected to perform well. Never submit the code for the code review before it is ready.
- Make sure the code compiles.
- Make sure the code passes all your bench tests.
- If your development tool does include code review tools, use them. In Visual Studio go to Project Properties, Code Analysis, select the Enable Code Analysis on Build checkbox and recompile.
- Make your code readable: Make sure the code is properly commented, indented and objects are appropriately named.
- Remove all code pollution: remove your to-do comments, temporary comments and unused/commented-out code.
- If your project includes modifications to an existing (production) code make a list of modified procedures and provide both the code before the change and the code with your changes.
- Send requirement documents, architecture and design documents together with your code. If your code does not implement requirements exactly add your list of differences with explanation. Do not include lengthy email exchanges that document responsibility for the requirement changes. If you created code tests, send them too.
- Read your code one more time before sending it for the review.
Do not wait with the code review request too long. If your project is bigger than a few hundredths or lines of code (LOC) it is certainly divided into some parts. Those parts and their interfaces are defined in design documents. Therefore, each code part can be reviewed right when it is finished. Asking for a code review early gives you the time to resolve issues between you and the reviewer without the embarrassment of involving anybody else.
The code does not have to be perfect before the code review. Yes, we asked you to do all in your powers to make it perfect; however, sometimes there are problems bigger than you. You can ask for the code review if you exhausted all the other options to get your code tamed. You can explain the problem and all the options you tried and ask for the code review. Just please never, never (!) ask for the code review of the broken code without telling the reviewer about the known bug.
Reviewer preparation
Make sure you have enough time to review the code properly. Take into account the size of the code, time the code took to develop, the amount of documentation. It is better to refuse the code review than to rubber stamp a risky code or to have the project testing or implementation waiting for you.
Do not plan to review much more code than 200 LOC in one session, nor a session to take longer than an hour.
Give the code enough time, even if this is just one line (usually a change). If the change implemented by the line deserved a project request it certainly does deserve your 5 minutes. Read the code trying to tell what it does. Then compare it with the requirement. Only after that read comments at the top of the unit to confirm the code, the requirement and the comment match. Use checklists (see below). Do not forget to look for missing things; those are hardest defects to spot.
If you do not see bugs, they might not be there. You are not supposed to turn in an expected yield of bugs; just to read the code diligently. On the other hand: do not forget that the more difficult code might naturally have more defects.
Do not be embarrassed if the author of the code is much more experienced than you are. A fresh eye comes always handy. You are going to learn a lot and you should not hesitate to ask questions. The answer will show if the thing you stumbled over is more useful to you or to the author.
Continued in Code Review Part 2)
Code Reviews aspects covering Readability
Feel free to leave any questions or comments below