INTRODUCTION TO SOFTWARE CODE REVIEWS
Code reviews are the way to get to efficient development of firmware and software. If you find yourself in the typical scenario below, you might enjoy reading more about the benefits of code reviews:
- You have gone past your deadlines and you have gone over your budget.
- The code base is large, disorganized, and unreadable.
- The code is full of bugs; the implementation of necessary features and requirements is still not complete.
- You’re almost there, but progress is slowing down.
- New team members can’t spin up fast enough to provide the necessary help to carry the project over the finish line.
You can avoid all of these problems. The solution is to use code reviews from the start of the project. Software code reviews are a great way to ensure efficient development of firmware/software. If the requirements and architecture give us the roadmap (as we read about Part 2), code reviews keep us on the defined path to the destination. Along our journey of development, the code reviews serve as the waypoints or milestones. Code reviews facilitate easier maintenance of the code base, enable smooth transitions to alternative platforms, and decrease the ramp-up time for support.
Where Are We Going?
To the code base. A code base is a living entity. It grows and changes as a project moves toward completion. As the project progresses, the code base must meet goals to maintain funding. Multiple team members have their hands in the development. It will encounter changes to requirements. All of the factors can combine to create a MONSTER! Every line of code matters, and mistakes are unavoidable. These mistakes can be caught and corrected early in the process through the use of code reviews. It’s the best route to get to efficient development of firmware/software.
Software code review is a process that the SIGMADESIGN firmware/software development team follows to ensure that code going into the code base gets a second look during development. After each task is complete, the developer submits the code for review. Other developers review the code, line by line. Not only is the code reviewed for correctness, it is also reviewed against the defined requirements and architecture. If we find no problems, great! The new code is merged into the code base. If there are problems, we make suggestions for changes or further discussion takes place. This process can take several iterations, but once every issue and potential issue is addressed, we merge the code and the development continues.
Staying on Track: Efficient development of firmware/software
You may be wondering, isn’t the code review process slow? Some developers might cringe at the thought of code review. It might appear to be unnecessary overhead. It could be seen as over-complication. Let’s address the concerns first and then how to solve them.
Concerns:
- Code review slows down code submissions.
- It takes time away from other developers.
- It can cause disagreements.
Solutions:
- Code reviews add some inevitable overhead which is minimized by planning ahead.
- Planning ahead will keep tasks small and focused.
- The system works and there is time for a discussion.
- There are plenty of tools that facilitate a streamlined review process, for example, Github, Gitlab, or Bitbucket.
BENEFITS OF SOFTWARE CODE REVIEWS
The many benefits of code review include a fresh set of eyes, ensuring that code adheres to standards, and it keeps the development team in sync. Fresh eyes can catch obvious mistakes that tired eyes might not see anymore. This saves unexpected debug time in the future.
A developer does not always catch system level mistakes. An outside perspective is helpful, as is a break from the primary assignment to review a team member’s work. Code reviews ensure adherence to requirements, architecture, and standards. If the code doesn’t adhere to standards, it is not allowed in the code base.
Code reviews keep the development team in sync. The whole team knows what each member is working on and we share best practices in this manner. We avoid system level conflicts and mitigate limitations. Informed priority decisions are made expediently without time-consuming meetings.
Most importantly, code review is a powerful motivator. It ensures accountability and prevents hacks. The product of code review is high quality code. High quality code is uniform and readable. The combination of a high quality code base and the practice of code review greatly reduces the spin-up time for new team members. It provides adequate protection from future mistakes, as well.
High quality code is easy to debug. It is difficult for time-snatching bugs to sneak into the code base with use of regular code reviews. The longer a bug exists, the greater the potential damage to the code base. Debugging typically takes the most time during any firmware/software development project. As a result, code review that leads to high quality code significantly reduces debugging time.
High quality code is not difficult to write, compared to the challenges of debugging poor quality code. Although debugging typically consumes the majority of development time we allocate to a software project, it is very difficult to accurately estimate the amount of time that we need for debugging.
MAINTAINING QUALITY CODE
A high quality code base is maintainable. This means that it does not require a considerable effort to:
- Add/modify features,
- Fix bugs,
- Address changing requirements,
- Make hardware platform changes.
Additionally, adaptation to changing requirements and future updates is much easier with code review.
Changing requirements is a fact. New features are desirable. Platform changes do occur. The qualities of uniformity and readability inherent to high quality code are informed by a strict adherence to conventions that are defined at the start of a project. These conventions include:
- Naming conventions,
- Indentations,
- Code structure,
- Documentation,
- There is no need to invent custom conventions, just use published conventions. Example: Clean Code by Robert C. Martin.
Consistency is the key. Consistent conventions make it easy for new and existing developers to make changes. Consistency and adherence makes it easy to debug code. We include debugging utilities and make sure that all modules are testable. “Spaghetti” code is not allowed. We divide code into intuitive modules with clear, uniform application programming interfaces (APIs). Non-uniform/non-readable code is fertile ground for mistakes. This leads to high feature development costs.
HIGH QUALITY CODE
High quality code is safe. It has built in protections against future mistakes. Without protection in the code base, bugs can survive for months. We make heavy usage of assertions whenever we make assumptions and depend on a module or hardware to behave as expected. The SIGMADESIGN firmware/software development team does not allow code that is difficult to understand and difficult to debug in the code base.
High quality code can easily be repurposed for future projects. High quality, maintainable code occurs when there is adherence to all of the previous elements of high quality code development. The application of adequate software abstractions is another way that we ensure the high quality of our code. Well abstracted code allows changes that do not necessitate major changes elsewhere in the code base. We define good requirements and design good architecture at the start of a project and ensure adherence with code reviews!
The importance of high quality code is immense. It is easy to jam code into a project to get close to completion. However, crossing the finish line can take longer than all other stages of a project combined when there is no code review. We ensure that we develop high quality code because we use code reviews.
CONCLUSION
We have our requirements, we have our architecture, and we have our roadmap. We know we must write code. Code reviews are an essential component of high quality code. They save time, which outweighs perceived overhead costs. The firmware/software development team at SIGMADESIGN uses this tool to ensure that it delivers extremely high quality code on time, always doing it the right way – not the long way. The SIGMADESIGN firmware/software development team is capable of dealing with changing requirements and deadlines and we always give our best to deliver the highest quality code.
Here is the Introduction to Firmware and Software Best Practices
You can read here: Part 1: Requirements of the Firmware & Software Best Practices
Or read here: Part 2: Software Architecture | Creating the Map