Bewährte Praktiken der Codeüberprüfung

Der Autor profitiert davon, dass er eine andere Perspektive auf seine Aufgabe bekommt und Code. Sie lernen oft neue Tricks oder entdecken einen möglicherweise optimaleren Weg zur Lösung eines bestimmten Problems. Außerdem können sie ihre Änderungen selbstbewusst einbringen, da sie wissen, dass andere Personen den Code auf Korrektheit geprüft haben und sich einig sind, dass alles in Ordnung ist.

Der Rezensent Sie profitieren davon, verschiedene Problemlösungsansätze in Aktion zu sehen. Sie werden auch ihre Fähigkeiten im Lesen von Code verbessern, was sehr wichtig ist, wenn sie sich z. B. in eine Bibliothek vertiefen, die für die Verwendung in einem Projekt. Die Überprüfung des Codes ist auch eine Lernmöglichkeit für den Prüfer wie für den Autor: Sie können auch neue Tricks lernen.

Die Team Das Team als Ganzes profitiert davon, da die Überprüfung einer Lösung für ein bestimmtes Problem ein Verständnis des Problems zumindest auf einer hohen Abstraktionsebene erfordert. Dies trägt dazu bei, zufällige Wissenssilos, die in einem Team entstehen können, abzubauen. Außerdem wird der "Bus-Faktor" erhöht: Da mindestens zwei Personen (vorzugsweise mehr) von einer bestimmten Änderung Kenntnis haben, ist die Wahrscheinlichkeit geringer, dass niemand im Team weiß, wie ein Modul zu aktualisieren ist, oder warum ein bestimmter Fehler auftritt.

Der Kunde profitiert von schnell und zuverlässig bereitgestellten Änderungen und Lösungen. Zusammen mit anderen Best Practices (wie z. B. umfassende Testabdeckung, CI/CD, Staging-Umgebungen usw.) stellen Code-Reviews auch sicher, dass das, was bereitgestellt wird, sicher und vernünftig ist und die Anforderungen wie angegeben erfüllt.

Zweck und Anwendung dieser Leitlinien

Bitte denken Sie daran, dass diese Vorschläge vor allem dazu dienen, ein Umfeld zu schaffen, das eine ehrgeizige und effiziente Problemlösung begünstigt, und gleichzeitig ein Sicherheitsnetz zu schaffen sowie Vertrauen und Transparenz bei jedem Teammitglied zu fördern.

Es wird zwar nachdrücklich empfohlen, dass sich ein Team an diese Leitlinien hält, aber sie sind nicht als harte und schnelle Regeln gedacht. Dieser Rahmen ist auch nicht als "Prozess" gedacht, der genau eingehalten werden muss, da starre Prozesse die Geschwindigkeit verringern und Verschwendung fördern.

Sie sind herzlich eingeladen, innerhalb Ihres Teams auf diesen Richtlinien aufzubauen. Denken Sie jedoch daran, dass Entwickler, die zwischen den Teams wechseln, erwarten werden, dass die Codeüberprüfung in jedem Team, dem sie beitreten, weiterhin auf diesem Dokument basiert. Dokumentieren Sie alle zusätzlichen Regeln und tragen Sie Verbesserungen, die besonders gut funktioniert haben, zu diesem Dokument bei.

Zuständigkeiten bei der Codeüberprüfung

Jeder im Team hat bestimmte Verantwortlichkeiten in Bezug auf die Codeüberprüfung. Nachfolgend werden bestimmte Gebote und Verbote der Codeüberprüfung je nach Rolle im Prozess dargelegt.

Projektleiter

• DO stellen Sie sicher, dass Ihre Repositories gut konfiguriert sind (z. B. sind Zusammenführungen in den produktionsnahen Zweig nicht ohne mindestens eine zustimmende Überprüfung erlaubt).
• DO Stellen Sie sicher, dass Ihr Team diese Praktiken versteht und anwendet, und arbeiten Sie aktiv daran, das Verständnis dafür zu fördern, warum wir Dinge auf eine bestimmte Weise tun.
• DO Achten Sie auf Gleichstandssituationen, in denen gegensätzliche Meinungen nicht ausgeräumt werden können: Als technischer Leiter Ihres Teams ist es Ihre Aufgabe, in solchen Fällen die bessere Lösung zu wählen und die Arbeit voranzutreiben.
• Allerdings, NICHT die Projektleitung als stumpfes Instrument einsetzen. NICHT "Rang abziehen". DO begrüßen Sie Kritik an Ihren Lösungen ebenso wie Sie sie an den Arbeiten anderer ermutigen.
• Erwägen Sie, eine GitHub-Integration in den Slack-Kanal Ihres Teams aufzunehmen. Dies kann hilfreich sein, um Überprüfungsanfragen besser auf den Radar der Überprüfer zu bringen, aber je nach Gesamtvolumen in Ihrem Kanal kann dies für Ihr Team das Richtige sein oder auch nicht.

Teammitglied

• Nehmen Sie an Code-Reviews teil. Es ist nicht akzeptabel, Code nicht zu überprüfen.
• Vergessen Sie nicht, Ihre Code-Reviews durchzuführen: Ihre Teamkollegen verlassen sich darauf, dass Sie mit ihrer Arbeit vorankommen!
• Wenn Sie eine bestimmte Überprüfung absolut nicht durchführen können, DO sie klar und offen kommunizieren.
• Allerdings, NICHT davon ausgehen, dass Sie eine bestimmte Überprüfung nicht durchführen können, weil Sie dieses Modul/diese Seite des Systems/diese Geschäftslogikspezifikation nicht kennen. Die Codeüberprüfung ist eine wichtige Lernmöglichkeit.
• Wenn Sie das Gefühl haben, dass Sie nicht genug über etwas wissen, um eine Rezension zu schreiben, DO Fragen Sie den Autor: Er wird Ihnen gerne erklären, was die Änderungen bewirken sollen.
• NICHT Bewertungen auf der Grundlage von Erfahrungswerten verweigern (Ihre oder des Autors).
• DO Versuchen Sie, mindestens so viele PRs zu überprüfen, wie Sie produzieren. Idealerweise sollten Sie das Verhältnis zwischen abgegebenen und erforderlichen Überprüfungen bei über 1 halten (insbesondere in größeren Teams).

Autor

• DO verstehen, dass es in Ihrer Verantwortung liegt, Ihren Code überprüfen zu lassen - Ihr Team kann proaktiv nach Pull-Requests zur Überprüfung suchen, muss es aber nicht.
• NICHT immer die gleichen Teammitglieder mit der Überprüfung beauftragen - Sie profitieren mehr von einem breit gefächerten Pool an Überprüfern (und umgekehrt profitiert eine größere Anzahl von Entwicklern von der Überprüfung Ihres Codes)
• NICHT jemanden aufgrund seiner Erfahrung von der Überprüfung ausschließen. Junior-Entwickler profitieren von der Überprüfung des Codes. Senior-Entwickler profitieren von der Überprüfung des Codes. Wie im Vorwort zu diesem Dokument erwähnt, alle von der Überprüfung des Codes profitiert.
• BERATEN SIE Verwendung eines Zufallsgenerators für die Auswahl der Prüfer. Z.B. in Ruby, %w[Mannschaftskamerad1 Mannschaftskamerad2 Mannschaftskamerad3].sample kann Wunder bewirken.
• DO Weisen Sie Ihren Pull-Anfragen mindestens zwei Prüfer zu, es sei denn, das ist absolut unmöglich. Auf diese Weise profitieren mehr Leute von dem Prozess (und mit drei Leuten ist es schwieriger, ein Unentschieden zu erreichen).
• DO Seien Sie bei Ihren Pull-Anfragen reaktionsschnell. Sie sollten zwar nicht Ihren Fluss unterbrechen, um sofort auf Kommentare zu antworten, aber stellen Sie sicher, dass Ihre Antworten zeitnah erfolgen - andernfalls werden Ihre PRs auf unbestimmte Zeit im Code-Review verweilen.
• DO bringen Sie eine offene Einstellung mit. Gehen Sie immer davon aus, dass Ihr Gutachter mit den besten Absichten zu helfen versucht. Erklären Sie Ihre Logik, gehen Sie auf die Argumente Ihres Gutachters ein und beantworten Sie seine Fragen.
• DO Höflich sein. Missverständnisse kommen vor, aber sie müssen nicht aus dem Ruder laufen und die Atmosphäre im Team beeinträchtigen.
• DO Seien Sie ehrlich. Wenn Sie glauben, dass dies die beste Lösung ist, dann sagen Sie es und legen Sie Ihre Argumente dar. Wenn Sie zu der Überzeugung gelangen, dass die Vorschläge Ihres Gutachters besser sind als das, was Sie erarbeitet haben, sagen Sie es ihm. Wenn Sie der Meinung sind, dass eine "beste Lösung aus beiden Welten", die sowohl Ihre als auch die Ideen des Überprüfers beinhaltet, erstellt werden kann, schlagen Sie diese vor. Letztendlich sollten Sie in Ihren Pull Requests auf einen Konsens hinarbeiten.
• DO Überlassen Sie die Klärung der Kommentare Ihrem Prüfer - lösen Sie sie nicht einfach, weil Sie überzeugt sind, dass es jetzt in Ordnung ist.
• DO Erläutern Sie Ihren Prüfern aktiv Ihre Aufgabe, Ihre Argumentation und andere Anforderungen. Es ist in Ordnung, nichts zu wissen - es ist nicht akzeptabel, Wissen vorzuenthalten.
• NICHT Wir sind alle großartige Spezialisten, aber es ist wichtig, eine gewisse Bescheidenheit mitzubringen, wenn man mit Ihnen zusammenarbeitet.
• DO Sei der erste Prüfer deines Codes. Setzen Sie sich eine Prüferkappe auf und scannen Sie den Code sorgfältig, so wie Sie es bei der Person tun würden, die Sie am wenigsten mögen. Identifizieren und eliminieren Sie die offensichtlichsten Dinge, wie leere Zeilen, Überbleibsel oder fehlende Spezifikationen. Überspringen Sie nichts - es wird höchstwahrscheinlich sowieso darauf hingewiesen werden. Verschwenden Sie nicht die Zeit der Prüfer!
• DO Beschreiben Sie Ihren Pull-Antrag gründlich. Eine Beschreibung ist gut, wenn der Prüfer beim Lesen des Codes nicht von irgendetwas überrascht wird. Denken Sie daran, dass er Ihre Gedanken nicht lesen kann. Deshalb ist es wichtig, Dinge zu beschreiben, die nicht offensichtlich sind, wichtige Entscheidungen mit Begründung oder alle neuen Klassen und Dateien.
• BERATEN SIE unter Verwendung der Pull-Request-Vorlage. Wenn Sie Github verwenden, fügen Sie es zu Ihrem Repository unter .github/pull_request_template.md. Es ermutigt alle Teammitglieder, ihre Pull-Anfragen zu beschreiben. Es ist auch viel einfacher zu schreiben, wenn Sie das Beschreibungsfeld mit einer Vorlage gefüllt haben. Hier finden Sie eine Vorlage, die wir in einem unserer Projekte verwenden https://gist.github.com/weemanjz/a20ccb9f3f492b9bd21ab026a1d46353

Autor

• DO verstehen, dass es in Ihrer Verantwortung liegt, Ihre Codeüberprüfung - Ihr Team kann proaktiv nach Pull-Requests suchen, um sie zu überprüfen, aber das muss es nicht.
• NICHT Bewertungen immer von denselben Personen anzufordern/zu vergeben Code-Reviewer - Sie profitieren mehr von einem breit gefächerten Reviewer-Pool (und umgekehrt profitiert ein breiteres Spektrum von Entwicklern von der Überprüfung Ihres Codes)
• NICHT jemanden aufgrund seiner Erfahrung von der Überprüfung ausschließen. Junior-Entwickler profitieren von der Durchführung Code-Überprüfungen. Senior-Entwickler profitieren von der Durchführung Code-Überprüfungen. Wie im Vorwort zu diesem Dokument erwähnt, alle profitiert von der Leistung Code-Überprüfungen.

Rezensent

• DO die Sprache der Anregung statt der Forderung zu verwenden. Anstatt zu sagen "Sie sollten Verbesserung der Codequalität indem ich stattdessen X tue"sagen "Haben Sie daran gedacht, die Code-Qualität indem ich X tue?"
• DO erläutern Sie Ihre Vorschläge. "Ich denke, dass X hier besser ist, weil es hilft, die Wissenstransfer und Verbesserung der Codequalität."
• Selbst wenn Ihr Vorschlag aus objektiven Quellen stammt (z. B. Code-Stil Leitlinien), DO den Autor auffordern, etwas zu tun, anstatt ihm zu sagen, dass er etwas tun soll. "Bitte halten Sie alle Widgets gemäß unserer Code-Stil Leitfaden - [Link]"
• NICHT davon ausgehen, dass Sie alles wissen. "Ich bin der Meinung, dass dieses Widget niemals frobifizieren sollte, und unter diesen Bedingungen wird es das tun - ist das eine Ausnahme, die eine Codeüberprüfung?"
• DO eine integrative Sprache verwenden. "Ich glaube, wir wären in Zukunft besser dran, wenn wir das so bauen würden. Was hältst du davon bessere Code-Überprüfung Anregung?" und "Vielleicht sollten wir hier stattdessen X für eine effektive Codeüberprüfung?"
• DO seien Sie pünktlich bei der Erledigung Ihrer Code-Überprüfungen. Sie sollten Ihren Flow nicht unterbrechen, aber versuchen, die Schleife möglichst eng zu halten. Manche Leute machen sie gerne zu Beginn oder am Ende ihres Arbeitstages, entweder als "Warm-up" oder als "Cooldown".

Bitte beachten Sie, dass diese Schlüsselwörter so eingefügt wurden, dass der Kontext und die Kohärenz des Textes erhalten bleiben. Wenn Sie sie an einer bestimmten Stelle haben möchten, geben Sie dies bitte an.