Codereview
Der Codereview ist eine Maßnahme zur Sicherstellung der Softwarequalität. Es handelt sich dabei um eine systematische Überprüfung existierenden Codes durch eine oder mehrere Personen mit dem Ziel, Fehler, Unklarheiten und sonstige Mängel in der Implementierung aufzudecken und entsprechende Verbesserungsvorschläge zu erarbeiten. Die Ergebnisse des Codereviews können direkt im Code umgesetzt werden und helfen so, diesen zu verbessern.
Bei der Entwicklung größerer Softwaresysteme sind qualitätssichernde Maßnahmen wie der Codereview wichtig. Bei SDQ werden Coderreviews regelmäßig durchgeführt, um die Qualität der dort angefertigten Implementierungsarbeiten zu sichern. Auf dieser Seite ist der Codereview-Prozess von SDQ beschrieben. Die aktuelle Planung von Codereviews ist der Planungsseite (für Mitarbeiter) zu entnehmen.
Überblick
Die folgende Tabelle zeigt den Ablauf eines Codereviews im Überblick:
| Phase | Review-Leiter | Code-Verantwortlicher | Reviewer | Protokollführer |
|---|---|---|---|---|
|
Zum Proposal bei BA/MA |
|
|
||
|
Vorbereitung |
|
|||
|
Review-Phase (1 Woche) |
|
|
|
|
|
Review-Treffen |
|
|
|
|
|
Nachbereitung |
|
|
Vorbereitung des Codereviews
Im Vorfeld des Codereviews sind einige Vorbereitungen zu treffen, die im folgenden beschrieben werden.
Verantwortlichkeiten
- Zunächst ist ein Code-Verantwortlicher festzulegen. Dies ist üblicherweise der Code-Ersteller, kann aber auch eine andere Person sein (insbesondere wenn es sich um älteren Code handelt und der Code-Ersteller nicht mehr da ist). Der Code-Verantwortliche erstellt eine Review-Anleitung, präsentiert den Code beim Codereview-Treffen und arbeitet die Ergebnisse des Reviews in den Code ein.
- Der Review-Leiter überprüft die Erfüllung von Aufgaben und die Einhaltung von Fristen (siehe sdqinternal:Codereview-Planung) und führt das Codereview-Treffen durch. Es sollte sich dabei nicht um einen Studenten, sondern um einen Mitarbeiter handeln; bei studentischen Implementierungsarbeiten sollte es möglichst der Betreuer sein.
- Eine oder mehrere Personen fungieren als Reviewer. Die Reviewer arbeiten den Code im Vorfeld durch und bringen ihre Verbesserungsvorschläge beim Codereview-Treffen ein. Der Review-Leiter ist für die Festlegung der Reviewer verantwortlich. Es gilt die Richtlinie, dass mindestens 1 Mitarbeiter (der Kobetreuer) und 2 Studenten als Reviewer eingesetzt werden sollen (ggf. mehr für Wissenstransfer, siehe Codereview-Organisation).
- Der Protokollführer erstellt das Protokoll des Codereview-Treffens. Er wird vom Review-Leiter bestimmt.
Bereitstellung des Codes
Der zu untersuchende Code wird den Reviewern 1 Woche vor dem Review-Treffen vom Code-Verantwortlichen zur Verfügung gestellt. Bei kleineren Programmen sind nach Absprache mit den Reviewern auch kürzere Fristen, etwa nur drei Tage, möglich.
Der Code-Verantwortliche sendet dazu den Reviewern eine E-Mail, mit welcher diese Zugriff auf den Code und die Review-Anleitung erhalten. Typischerweise gibt der Verantwortliche mit der E-Mail Zugriff auf die Repositories, wo sich Code und Review-Anleitung befinden. Damit Code-Verantwortliche bis zum Review weiter am Code arbeiten können, ohne dass durch diese Änderungen die Reviews ständig überarbeitet werden müssen, gibt der Verantwortliche in der E-Mail außerdem den Commit an, welcher dem zu überprüfenden Stand des Codes entspricht. Diese Angabe ist entweder die Commit-ID, oder ein spezieller Tag (Anleitungen für Git und SVN).
Eine Kopie der Mail geht an den Review-Leiter, damit dieser die fristgerechte Bereitstellung des Codes überprüfen kann.
Bereitstellung einer Review-Anleitung
Zusammen mit dem Code sendet der Code-Verantwortliche den Reviewern eine Review-Anleitung mit den folgenden Inhalten:
- Eine kurze Erklärung die beschreibt was der Code macht und in welchen Projektkontext er eingebettet ist (ggf. reicht ein Verweis auf bestehenden Text / Proposal)
- Anleitung zur Erstellung und Ausführung des Codes: Beinhaltet die Angabe benötigter Libraries und Tools mit Installationsanleitung. Das Ausprobieren des entwickelten Tools / der entwickelten Funktionalität durch die Reviewer ist allerdings nur optional, der Fokus sollte auf der Prüfung des Codes liegen (dies sollte auch in der Anleitung hervorgehoben sein).
- Anleitung zur Prüfung des Codes: Beinhaltet die Angabe, welche Codeteile neu bzw. zu prüfen sind. Weitere Hinweise (generelle Funktionsweise des Codes, Schlüsselstellen etc.) sind wünschenswert.
Die Review-Anleitung ist ebenso wie der Code 1 Woche vor dem Review-Treffen zur Verfügung zu stellen. Vollständigkeit und fristgerechte Abgabe werden vom Review-Leiter überprüft.
TODO: Beispiel für Review-Anleitung angeben
Anmerkung: nicht bloss auf Quellen im WWW Verweisen - Als PDF-Ausdruck beilegen für den Fall, dass die Originalseite offline ist oder aber die Reviewer offline sind.
Überprüfung des Codes
Nach der Bereitstellung des Codes und der Review-Anleitung haben die Reviewer 1 Woche lang Zeit, den Code zu überprüfen (Richtlinie für den Zeitaufwand: 2-3 Stunden). Dabei sind beispielsweise die folgenden Fragen begründet zu beantworten:
- Sind der Zweck und die generelle Funktionsweise des Codes bekannt bzw. nachvollziehbar?
- Ist der Code vollständig und verständlich dokumentiert? Gibt es Stellen, deren Bedeutung und / oder Funktionsweise unklar bleibt? Sind auch vorhandene Testfälle dokumentiert?
- Ist die Architektur des Codes klar, verständlich und dokumentiert? Sind größere Architekturzusammenhänge durch Abbildungen illustriert?
- Sind die bei SDQ vereinbarten Richtlinen zur Qualitätssicherung eingehalten?
- Gibt es Stellen, an denen die Implementierung einfacher / allgemeingültiger / performanter / modularer sein könnte?
- Wenn der Code auch ausgeführt wurde: Lässt sich der Code fehlerfrei ausführen?
- Kann die korrekte Funktion des Codes durch Ausführen der Anwendung bzw. vorhandener Testfälle (Unit Tests, siehe JUnit) nachvollzogen werden?
Bei der Beantwortung dieser Fragen können auch die weiter unten aufgeführten Weblinks zu den Themen Codeformatierung und Codestyle hilfreich sein.
Falls die Funktionalität des Code unklar ist, kann beim Codeverantwortlichen auch nachgehakt werden. Das Ausführen des Tools kann evtl. auch Aufschluss über den Zweck und die Funktionsweise geben.
Die Reviewer senden die Ergebnisse ihrer Untersuchung bis zum Review-Treffen per E-Mail an den Review-Leiter. Dieser prüft, ob tatsächlich sinnvolle Reviews durchgeführt wurden.
Durchführung des Codereviews
Im Zentrum des Codereviews steht ein gemeinsames Treffen aller Beteiligten. Der Review-Leiter legt den Termin fest und führt durch das Treffen; der Protokollführer hält die anwesenden Teilnehmer und die Ergebnisse des Treffens fest. Der Code-Verantwortliche präsentiert den Code über Beamer; Verbesserungsvorschläge werden von den Reviewern eingebracht und diskutiert. Das Treffen sollte auf 1 Stunde angesetzt werden.
Nachbereitung des Codereviews
Die Nachbereitung des Reviews hängt von den festgestellten Ergebnissen ab:
- Wurden lediglich kleine Mängel festgestellt, können sie vom Code-Verantwortlichen direkt behoben werden. Der Review-Leiter ist dafür verantwortlich, die Behebung der Mängel nach einer mit dem Code-Verantwortlichen festgelegten Zeitspanne (Richtlinie: 1 Woche) zu überprüfen. Der Review-Leiter meldet den erfolgreichen Abschluss des Reviews an die QS-Beauftragten.
- Bei schwerwiegenden Mängeln bzw. hohem Zeitaufwand für die Einarbeitung der Verbesserungen ist ein erneuter Termin für ein Code-Review festzulegen (Richtlinie: 1 Monat später). Der Code-Verantwortliche nutzt die Zeit bis zum erneuten Review zur Einarbeitung der Verbesserungen; das Protokoll des ersten Reviews dient beim nachfolgenden Review als Grundlage für die Überprüfung der gemachten Fortschritte.
Architektur-Reviews
Zu Beginn oder in der Startphase einer Implementierungsarbeit ist es sinnvoll, ein Architektur-Review durchzuführen. Gegenstand der Untersuchung ist hier nicht (hauptsächlich) der vorhandene Code, sondern die geplante Architektur. Das Review dient dazu, eventuell vorhandene Mängel in der Architektur vor deren Implementierung aufzudecken.
Ziele:
- Aufdeckung von Architekturmängeln
- Weitergabe von Architekturwissen
- Kennenlernen von Architekturmustern
Das Architektur-Review wird von mindestens einem Mitarbeiter (!= Betreuer) sowie Studenten durchgeführt, welche die geplante Architektur prüfen und auf eventuelle Mängel hinweisen.
Die Ergebnisse des Reviews werden in einem Protokoll festgehalten, und die Durchführung des Reviews wird an die QS-Beauftragten gemeldet.
Beispiele
TODO: Beispiel für Review-Anleitung angeben
Weblinks
Protokolle
Codeformatierung
Folgende Formatierungsrichtlinien sollten von Studenten eingehalten werden:
- Oracle Java Conv: Code Conventions for the Java Programming Language (Vorgabe von Oracle, archived)
- Google Java Conv: Java Style Guide
Codestyle
- Design Patterns: können helfen Quellcode flexibler, erweiterbarer und verständlicher zu machen
- Wikipedia ENG: Buch von Erich Gamma et al., die klassischen Design Patterns mit vielen Beispielen
- Bad Smells: beschreiben generell zu vermeidende Strukturen des Quellcodes, die erfahrungsgemäß zu schlechter Wartbarkeit oder Verstehbarkeit führen. "Bad Smells" können durch Refactoring beseitigt werden.
- Liste von Bad Smells
- ReSharper (Visual Studio Add-In zum Refactoring von C#-Code)
- IDEA (Java Entwicklungsumgebung mit eingebauten Refactoring-Funktionen)
- Refactoring Website
- Refactoring-Buch bei Amazon.de