Code Review mit Doxygen und SVN?

Ich arbeitete gegenwärtig an einem Firmwareprojekt zu dem ich erst dazustieß, nachdem der größte Teil des Codes bereits geschrieben war. Da ich nicht an der Entwicklung der bis zu diesem Zeitpunkt implementierten Firmwaremodule mitgewirkt hatte und ich daher noch relativ unbefangen war, wurde ich gebeten mich dem Thema Code Review anzunehmen. Die Prozesse unseres Kunden geben vor, dass ein Codereview durchgeführt und dokumentiert werden muss. Der Auftraggeber gibt in seinem Code Review Prozess allerdings keine detaillierten Vorgaben zu den Themen:

• Wie soll das Code Review durchgeführt werden?
• Wie soll das Review dokumentiert werden?
• Welche Tools sollen für das Review eingesetzt werden?

Aus diesem Grund diskutierten wir zunächst, in einer Runde bestehend ausschließlich aus Firmwareentwicklern, darüber wie wir uns diesen Vorgang wünschen würden. Ich hatte damals in Zusammenhang mit Code Review bereits Erfahrungen mit einem ticketbasierten Tool gemacht und war von Rückverfolgbarkeit und Übersichtlichkeit eher ernüchtert. Da wir zum damaligen Zeitpunkt in unserem Projekt zudem stark unter Zeitdruck standen, versuchten wir einen möglichst pragmatischen Ansatz zu wählen.

Code Review mit Doxygen

Zur Dokumentation des Codereviews entschieden wir uns Doxygen zu verwenden. Hierbei handelt es sich um ein Tool, dass zum einen in unserem Projekt bereits jeder Entwickler für die Dokumentation seines Codes verwendet. Zum anderen genießt Doxygen unter Firmwareentwicklern eine extrem hohe Akzeptanz. Während sich viele Entwickler z.B. in stundenlangen Diskussionen über die Vor- und Nachteile von GIT gegenüber SVN (und andersrum) verlieren können, wird man kaum einen Soft- oder Firmwareentwickler treffen, der nicht einverstanden mit der Verwendung von Doxygen Kommentaren in einem Projekt ist. Viele Entwickler verstehen Doxygen allerdings eher als Konvention, wie ein Code einheitlich und lesbar zu dokumentieren ist (was natürlich für sich alleine schon eine große Bereicherung ist). Mit dem Erzeugen der eigentlichen Doxygen Builds, und den damit verbundenen Möglichkeiten, beschäftigen sich dabei nur die wenigsten.

Zur Dokumentation der Code Reviews verwenden wir den Befehl xrefitem (siehe auch https://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdxrefitem). Dieser Befehl dient zum Anlegen von benutzerdefinierten Listen im Doxygen Output (zum Beispiel im HTML-Format).  Mit diesem Befehl ist es möglich automatisch bei jedem Build eine eigene Liste mit Code Review Kommentaren, für jede getestete Unit zu erzeugen. Soll zum Beispiel für das Modul LED (bestehend aus LED.c und LED.h) eine Liste mit Review Ergebnissen angelegt werden, kann folgender Kommentar verwendet werden:

Die Kommentare werden dabei im Code direkt an derjenigen Stelle, an der ein Fehler gefunden wurde eingefügt. Im gezeigten, zugegebener Weise eher trivialen Beispiel, führt eine redundante Abfrage des Übergabeparameters led zu nicht erreichbarem und daher unnötigen Code. Hierdurch wird der Code nicht nur aufgebläht und unnötig kompliziert, es verhindert zudem, dass beim Unittest eine vollständige Testabdeckung erreicht wird. Die Zeile:

ledToggled=false;

wird niemals ausgeführt. Erzeugt man nun einen Doxygen Build des Projekts und schaut sich den HTML-Output der Datei LED.c an, so fällt auf, dass der Review Kommentar in die Dokumentation der Funktion aufgenommen wurde:

Zudem wurde eine Liste mit dem Titel led_review erzeugt. Wie in der Abbildung weiter unten zu erkennen ist, listet diese nicht einfach nur die Kommentare auf, sondern gibt zusätzlich an, auf welches Element sich der Kommentar bezieht (in diesem Fall Function LED_toggleLed). Da die Liste als eigene HTML-Datei vorliegt, kann diese – falls ein Word-Template für Code Review Dokumentation existiert – direkt in dieses integriert werden. Wird, wie in unserem Falls, ein zentraler Buildserver verwendet, kann dieser auch so konfiguriert werden, dass der Doxygenbuild automatisch in den Buildprozess integriert wird. So muss der Reviewer den Code nur einchecken und einen Build des gesamten Projekts anstoßen. Die Doxygen-Outputs fallen dann als Artefakte des jeweiligen Buildprozess an.

Zwar könnte der zuständige Entwickler nun diese Liste verwenden, um die einzelnen Stellen im Code zu identifizieren, welche einer Überarbeitung bedarf. Es hat sich in unserem Fall jedoch als praktikabel erwiesen, direkt nach den Wörtern Code Review in der entsprechenden Datei oder im gesamten Projekt zu suchen.

Rückverfolgbarkeit erreichen mit SVN

Natürlich bietet unsere Lösung, so wie sie bis jetzt beschrieben wurde, noch keinerlei Möglichkeit die Änderungen auf Grund der Review-Kommentare nachzuvollziehen. Hierfür haben wir in unserem Projekt die Dokumentation mit einem Tool zur Versionsverwaltung kombiniert. Dabei würde sich GIT prinzipiell genauso gut eignen wie SVN. Da wir in unserem Projekt allerdings SVN verwenden, spreche ich im Folgenden ausschließlich darüber.

Nachdem der Entwickler ein Modul zum Code Review freigegeben hat, geht der Reviewer durch den Code und kommentiert zunächst alles mit dem entsprechenden Doxygen Befehl, was seiner Meinung nach einer Änderung bedarf. Anschließend wird die so modifizierte Variante ins SVN eingecheckt, und ein Doxygen Build angestoßen. Auf diese Weise wird automatisch eine Liste mit allen Review-Kommentaren erstellt. Der Kommentar zum Commit sollte dabei einen Hinweis auf die Codereview-Kommentare beinhalten. Die so entstandene SVN Revision wird, zusammen mit dem Autor der Review Kommentare, sowie dem Datum des Reviews, in der Liste mit Code Review-Kommentaren ergänzt. Außerdem sollten die genauen Pfade, unter denen die Dateien im SVN zu finden sind, enthalten sein.

Nach durchführen eines SVN-updates, sieht der zuständige Entwickler nun direkt im Code, welche Stellen geändert werden sollten und kann ohne Verwendung eines weiteren Tools die Bearbeitung durchführen. Auch nach den Änderungen im Code dürfen die Review Kommentare durch den Entwickler selber nicht gelöscht werden. Der Entwickler hat allerdings die Möglichkeit Kommentare abzulehnen, indem er den Review Kommentar mit einer entsprechenden Erklärung ergänzt. Nachdem die Kommentare im Code umgesetzt wurden, checkt der Entwickler die neue Fassung des Moduls erneut ins SVN ein. Auch diese SVN Revision wird im Codereview Protokoll mit Datum und Autor vermerkt.

Im letzten Schritt kontrolliert der Reviewer, ob auf Grund aller Kommentare die nötige Änderung erfolgt ist. Ist das Problem zufriedenstellend gelöst worden, wird der Kommentar gelöscht. Lässt sich das Problem nicht – oder zumindest zurzeit nicht – lösen, kann der Review Kommentar durch einen anderen Kommentar ersetzt werden. Hierbei bietet sich an erneut auf xrefitem zurückzugreifen. So können alle verbleibenden bugs oder todos automatisch in einer entsprechenden Liste zusammengefasst werden. Auf der oben angegebenen Quelle findet sich zum Beispiel folgendes Beispiel für einen Kommentar zur automatischen Generierung von Todo Listen:

\xrefitem todo „Todo“ „Todo List“

Wurden alle Kommentare vom Entwickler geprüft, der Code entsprechend geändert und wurden diese Änderungen vom Reviewer überprüft, kann das Review abgeschlossen werden. Hierfür wird die resultierende dritte Revision ohne Review- (aber ggf. mit Todo-) Kommentaren ins SVN eingecheckt. Erneut wird die neue Revision, der Autor und das Datum vermerkt.

Um die Änderungen nachvollziehen zu können reicht ein diff der drei Revisionen. Wird zum Beispiel ein Diff der Review- zur Check-Revision durchgeführt, kann direkt im Code nachvollzogen werden, was sich auf Grund des Kommentars geändert hat.

Dokumentation des Reviews

Das Ergebnis des Codereviews eines Moduls, sollte ein Protokoll sein, das alle Codereview-Kommentare (also den Doxygen HTML-Output) enthält. Neben den Kommentaren sollten außerdem wie beschrieben die SVN-Pfade sowie Revisionen von Review, Fix und Check vermerkt sein. Es sollte klar ersichtlich sein, wer welche Aufgabe übernommen hat und wann diese durchgeführt wurden. In unserem Fall gibt es zudem ein vom Kunden vorgegebenes Dokument in dem die Reviews für das ganze Projekt aufgelistet werden müssen. In diesem wird nach Abschluss des Reviews eines Moduls das entsprechende Review Protokoll verlinkt. Mit Hilfe dieser ist es dann möglich, folgende Fragen zu beantworten.

• Was ist beim Review der einzelnen Module aufgefallen?
• Was wurde auf Grund der Kommentare unternommen?
• Wer war für die Bearbeitung der einzelnen Schritte verantwortlich und wann wurden diese durchgeführt?
• Gibt es noch offene Todos?

Fazit

Beim vorgeschlagenen Vorgehen für Code Review Kommentare handelt es sich um ein sehr pragmatisches Vorgehen, welches dem Entwickler ermöglicht sich mit keinem Tool auseinandersetzen zu müssen, welches er nicht bereits verwendet (die Verwendung von Doxygen und einem Tool zur Versionsverwaltung vorausgesetzt). Durch die Zuordnung von SVN-Revisionen erreichen wir durch unser Vorgehen außerdem eine sehr gute Rückverfolgbarkeit.

Auch wenn sich das Vorgehen bis jetzt als praktikabel erweist, ist unser Projekt noch lange nicht abgeschlossen, so dass viele Erfahrungswerte noch ausstehen. Ich freue mich daher sehr über jede Anmerkung und jeden Verbesserungsvorschlag von anderen Entwicklern, vor allem aber auch über Bewertungen aus dem Qualitätsmanagement 😊.

Viele Grüße,

Björn Schmitz

PS:

Als neues Mitglied der MEDtech Ingenieure werde ich regelmäßig über Erfahrungen und Projekte schreiben. Mehr über mich erfahren Sie auf Über Uns.