Code review with Doxygen and SVN?

I was currently working on a firmware project, which I joined after most of the code had already been written. Since I hadn't been involved in the development of the firmware modules implemented up to that point and was therefore still relatively new to the project, I was asked to take on the topic of code review. Our client's processes stipulate that a code review must be conducted and documented. However, the client doesn't provide detailed specifications on the following topics in their code review process:

• How should the code review be carried out?
• How should the review be documented?
• Which tools should be used for the review?

For this reason, we initially discussed, in a group consisting exclusively of firmware developers, how we would like this process to work. I had already had experience with a ticket-based tool for code review at the time and was rather disappointed by the traceability and clarity. Since we were also under severe time pressure in our project at the time, we tried to take the most pragmatic approach possible.

Code review with Doxygen

We decided to use Doxygen to document the code review. This is a tool that every developer in our project already uses to document their code. It also enjoys extremely high acceptance among firmware developers. While many developers can lose themselves in hours of discussions about the advantages and disadvantages of GIT versus SVN (and vice versa), you'll hardly find a software or firmware developer who disagrees with the use of Doxygen comments in a project. However, many developers understand Doxygen more as a convention for documenting code in a consistent and readable manner (which, of course, is a great asset in itself). Very few actually concern themselves with creating the actual Doxygen builds and the associated possibilities.

To document the code reviews we use the command xrefitem (See also https://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdxrefitem). This command is used to create custom lists in Doxygen output (for example, in HTML format). This command allows you to automatically generate a separate list of code review comments for each tested unit during each build. For example, if you want to create a list of review results for the LED module (consisting of LED.c and LED.h), you can use the following comment:

The comments are inserted into the code directly at the point where an error was found. In the admittedly rather trivial example shown, a redundant query of the transfer parameter led to unreachable and therefore unnecessary code. This not only bloats and unnecessarily complicates the code, but also prevents complete test coverage from being achieved during unit testing. The line:

ledToggled=false;

is never executed. If you now create a Doxygen build of the project and look at the HTML output of the LED.c file, you'll notice that the review comment has been included in the function's documentation:

Additionally, a list titled led_review was created. As can be seen in the figure below, this doesn't just list the comments, but also specifies which element the comment refers to (in this case, the LED_toggleLed function). Since the list is available as a separate HTML file, it can be integrated directly into a Word template for code review documentation if one exists. If, as in our case, a central build server is used, it can also be configured to automatically integrate the Doxygen build into the build process. This way, the reviewer only has to check in the code and initiate a build of the entire project. The Doxygen outputs are then generated as artifacts of the respective build process.

Although the responsible developer could now use this list to identify the individual places in the code that require revision, in our case it has proven practical to directly after the words Code Review to search in the corresponding file or in the entire project.

Achieve traceability with SVN

Of course, our solution, as described so far, doesn't yet offer any way to track changes based on review comments. For this purpose, we combined the documentation with a version control tool in our project. In principle, GIT would be just as suitable as SVN. However, since we use SVN in our project, I'll talk exclusively about it below.

After the developer releases a module for code review, the reviewer goes through the code and first comments on everything they believe needs to be changed using the appropriate Doxygen command. The modified version is then checked into SVN, and a Doxygen build is initiated. This automatically creates a list of all review comments. The commit comment should include a reference to the code review comments. The resulting SVN revision, along with the author of the review comments and the date of the review, is added to the list of code review comments. The exact paths where the files can be found in SVN should also be included.

After performing an SVN update, the responsible developer can now see directly in the code which sections need to be changed and can make the changes without using any additional tools. Even after making changes to the code, the review comments may not be deleted by the developer themselves. However, the developer has the option of rejecting comments by adding a corresponding explanation to the review comment. After the comments have been implemented in the code, the developer checks the new version of the module back into SVN. This SVN revision is also noted in the code review log with the date and author.

In the final step, the reviewer checks whether the necessary changes have been made based on all comments. If the issue has been satisfactorily resolved, the comment is deleted. If the issue cannot be resolved—or at least not at the moment—the review comment can be replaced with another comment. It's a good idea to use xrefitem again for this. This allows all remaining bugs or todos to be automatically summarized in a corresponding list. The source cited above provides the following example of a comment for automatically generating to-do lists:

\xrefitem todo “Todo” “Todo List”

Once all comments have been reviewed by the developer, the code has been modified accordingly, and these changes have been approved by the reviewer, the review can be completed. To do this, the resulting third revision is checked into SVN without any review comments (but possibly with to-do comments). The new revision, author, and date are noted again.

To understand the changes, a diff of the three revisions is sufficient. For example, if a diff is performed between the review and check revisions, you can see directly in the code what has changed as a result of the comment.

Documentation of the review

The result of a module's code review should be a log containing all code review comments (i.e., the Doxygen HTML output). In addition to the comments, the SVN paths and revisions of the review, fix, and check should also be noted, as described. It should be clearly visible who performed which task and when it was completed. In our case, there is also a document specified by the client in which the reviews for the entire project must be listed. After the completion of the module review, the corresponding review log is linked to this document. This log then makes it possible to answer the following questions.

• What did you notice when reviewing the individual modules?
• What was done in response to the comments?
• Who was responsible for processing the individual steps and when were they carried out?
• Are there any open todos?

Conclusion

The proposed approach for code review comments is a very pragmatic one, allowing developers to avoid having to deal with any tool they don't already use (assuming Doxygen and a version control tool are used). By assigning SVN revisions, our approach also achieves excellent traceability.

Even though the approach has proven practical so far, our project is far from complete, so much experience is still pending. I therefore greatly appreciate any comments and suggestions for improvement from other developers, but especially feedback from quality management 😊.

Best regards,

Björn Schmitz

PS:

As a new member of MEDtech Engineers, I will be writing regularly about my experiences and projects. Learn more about me at About Us.