Ich stieß auf ein Dokument mit Regeln und Empfehlungen zum Prozess der Codeüberprüfung im Unternehmen. Ich entschied, dass solche nützlichen Informationen mit der Außenwelt geteilt werden sollten. Mit dem Segen des
Autors veröffentliche ich die Arbeit.
Die meisten dieser Regeln sind beratender Natur und sollten in erster Linie vom gesunden Menschenverstand und nicht von der blinden Einhaltung geleitet werden.
Allgemeine Bestimmungen
- In hh.ru erfolgt die Überprüfung im Pull-Request-Format auf Github.
- Überprüfungs- und Pull-Anforderungen sind erforderlich, auch wenn im Rahmen der Aufgabe eine Zeile oder ein Zeichen im Code geändert wird.
- Jede Aufgabe muss mindestens einen verantwortlichen Prüfer haben. Sie wird in der Aufgabe als Prüfer angegeben und ist wie der Autor für den Code verantwortlich. Nicht verboten und ermutigt, an der Überprüfung anderer Personen teilzunehmen.
- Die Verantwortung für die Durchführung der Aufgabe durch die Überprüfung liegt beim Autor der Aufgabe.
- Änderungen nach einer Überprüfung, z. B. Änderungen während des Tests, sollten ebenfalls in der Vorschau angezeigt werden.
Ziele überprüfen
- Verbreitung von Erfahrung und Wissen zwischen Entwicklern.
- Unterstützung des Prinzips - Änderungen sollten den vorhandenen Code nicht verschlechtern, sondern verbessern.
- Korrektur von Logikfehlern und Sicherheitsfehlern, korrekte Behandlung von Ausnahmen.
- Verbesserung der Codequalität, Wartbarkeit und Projektarchitektur.
- Verbesserung der Lesbarkeit von Code.
- Verbesserung der Testabdeckung und Testen auf dem richtigen Niveau.
- Dokumentation verbessern.
- Übereinstimmung der Änderungen mit den Anforderungen in der Aufgabe.
- Verhinderung von technischen Schulden oder technischen Steuern.
- Das durchdachte Design der API, wobei die API ein beliebiges Modul mit einer externen Schnittstelle ist. Zum Beispiel, dass eine Ressource in einem Dienst eine gut durchdachte URL, ein praktisches JSON-Format, korrekte Antwortcodes in verschiedenen Fällen usw. hat.
- Die korrekte Historie der Commits in der Gita mit Nachrichten, die das Wesentliche der Nachricht widerspiegeln, ohne temporäre Commits.
Vorbereitung für die Überprüfung
- Lesen Sie Ihren Code 2-3 Mal, bevor Sie eine Pull-Anfrage veröffentlichen: Mit hoher Wahrscheinlichkeit werden Sie dort selbst Fehler finden, die dem Prüfer Zeit sparen. Stellen Sie sicher, dass keine Fehler vorhanden sind, die automatisch erkannt werden können - Fehler im Codestil, abgebrochene Tests. Stellen Sie sicher, dass der Code keine temporären Kommentare und keinen Debugging-Code enthält, und überprüfen Sie, ob Ihr Code mit den akzeptierten Styleguides übereinstimmt.
- Wenn Sie während der Arbeit an einer Aufgabe eine Pull-Anforderung erstellen, schreiben Sie "[WIP]" in die Überschrift und setzen Sie ein "Work in Progress" -Zeichen. Wenn die Arbeit beendet ist, entfernen Sie die Tags und informieren Sie sie in einem separaten Kommentar, damit Interessenten wissen, dass der Code angezeigt werden kann.
- Seien Sie bereit, dem Rezensenten eine Mini-Demo zu dieser Aufgabe zu zeigen.
- Geben Sie kleine Teile des Codes zur Überprüfung. 200-300 Änderungszeilen - die Grenze für eine effektive Überprüfung.
- Nehmen Sie unabhängige Änderungen in separaten Commits vor.
- Beschreiben Sie Commits mit kurzen und informativen Nachrichten.
- Wenn Sie das Refactoring als separates Commit durchführen, ist es einfacher, Änderungen in der Logik und im Wesentlichen der Aufgabe zu erkennen.
- Formatieren Sie den Code als separates Commit vor größeren Änderungen oder sogar als separate Pull-Anforderung.
- Nehmen Sie keine geringfügigen Änderungen vor. Fügen Sie beispielsweise Zeilenumbrüche in eine Datei ein, in der Sie nichts anderes geändert haben.
- Beschreiben Sie im Titel der Pull-Anfrage kurz und informativ das Wesentliche der Änderungen.
- Beschreiben Sie das Problem und die Lösung in der Pull-Anforderung. Beschreiben Sie alternative Lösungen und warum die aktuelle Lösung ausgewählt ist. Wenn sich die Änderungen auf die Benutzeroberfläche beziehen, fügen Sie Screenshots "vor" und "nach" hinzu.
- Geben Sie in der Pull-Anforderung einen Link zur Aufgabe und in der Aufgabe einen Link zur Pull-Anforderung an.
- Manchmal ist es hilfreich, die gewählte Lösung mit dem Prüfer zu besprechen, bevor Sie den Code schreiben. Dies hilft, die beste Lösung für das Problem zu finden und den Überprüfungsprozess zu vereinfachen.
Auswahl der Prüfer
- Geben Sie die Aufgabe der Überprüfung einem Spezialisten auf dem betreffenden Gebiet.
- Wenn mehrere Befehle mit Code funktionieren, ist es hilfreich, einen Prüfer aus einem anderen Team auszuwählen, um Wissen zu verbreiten.
- Der Bewährungshelfer ist möglicherweise nicht der verantwortliche Prüfer, kann jedoch am Überprüfungsprozess teilnehmen.
- Geben Sie nicht alle Ihre Aufgaben für die Überprüfung an dieselben Personen weiter - fordern Sie Bewertungen von verschiedenen Personen an.
- Wenn es sich bei dem Problem um einen nicht trivialen Code handelt, den eine bestimmte Person versteht, zeigen Sie ihm die Änderungen an, unabhängig davon, wer der verantwortliche Prüfer ist. Denken Sie auch daran, dass jedes Repository über Betreuer verfügt, die mehr über diesen Code wissen und die Entwicklung überwachen.
- Der Rest des Gutachters wird im gegenseitigen Einvernehmen der Parteien willkürlich ausgewählt. Verwenden Sie die Empfehlungen auf dem Github, die auf der „Schuld“ des betroffenen Codes basieren, um Ihnen bei der Auswahl zu helfen.
- Nachdem Sie einen Prüfer ausgewählt haben, geben Sie ihn in der Pull-Anforderung als Beauftragten an. Eine Liste aller Pull-Anforderungen, die Ihnen zugewiesen sind.
Überprüfungsprozess, Allgemein
Bezieht sich sowohl auf den Autor des Codes als auch auf den Prüfer.
- Der gesamte Code ist üblich, es gibt keine Konzepte wie "Mein Code" oder "Ihr Code". Dies bedeutet, dass jeder Entwickler für jede Codezeile verantwortlich ist und nicht nur derjenige, der diese Zeile geschrieben hat.
- Schaffen Sie eine Atmosphäre des gegenseitigen Verständnisses, seien Sie höflich und freundlich, schätzen und respektieren Sie einander, setzen Sie Ihre Meinung nicht durch. Hören Sie auf die Meinung des Gegners und vertreten Sie nicht Ihren Grundsatz. Machen Sie die Bewertung nicht zu einer negativen Erfahrung für Kollegen.
- Stellen Sie Fragen, wenn etwas nicht klar ist. Argumentieren und Fragen und Antworten angeben. Dem Autor des Codes ist möglicherweise nicht klar, was unter der Frage „Warum ist das so?“ Zu verstehen ist. Der Prüfer versteht jedoch die Argumentation der Antwort „nicht einverstanden“ nicht.
- Dehnen Sie den Überprüfungsprozess nicht aus, sparen Sie Zeit, reagieren Sie schnell auf Kommentare, diskutieren Sie mündlich, provozieren Sie keine langen Diskussionen und züchten Sie keine „Holivars“. Wenn Sie nicht schnell zu einem Konsens gelangen können, wenden Sie sich an Ihre Kollegen, den Betreuer oder den Manager des Funktionsbereichs.
- Wenn sich die Aufgabe nicht in mehreren Zeilen befindet, verbringen Sie 10 bis 15 Minuten mit dem Prüfer bei einer gemeinsamen Codeüberprüfung. Dies ist bereits vor dem Erstellen einer Pull-Anforderung hilfreich. Besprechen Sie die Essenz der Aufgabe und Lösung, sehen Sie, wie sie in einer Arbeitsumgebung war und wurde. Dies hilft dem Prüfer, besser in den Kontext der Aufgabe einzutauchen. Die meisten Kommentare bleiben ungeschrieben, was allen Zeit spart.
- Beschreiben Sie nach einer mündlichen Diskussion immer die getroffene Entscheidung und die Gründe dafür in der Pull-Anfrage. Die Verantwortung für die Beschreibung liegt beim Autor des Codes.
- Wenn der Code dieselbe Art von Fehlern enthält, sollte sich der Prüfer im ersten oder zweiten Kommentar auf die Aufmerksamkeit des Autors des Codes konzentrieren, ohne jeden Eintrag zu kommentieren, und der Autor sollte den Code vor Veröffentlichung der Korrektur auf dieselbe Art von Fehlern analysieren.
- Lob für die erfolgreichen Entscheidungen des Autors und die Vorschläge des Rezensenten.
- Hinterlassen Sie Kommentare zu den Änderungen in der Pull-Anforderung selbst und nicht zu einzelnen Commits. Somit befindet sich die gesamte Korrespondenz an einem Ort, auch nach dem Rebase.
- Antworten Sie auf Kommentare in denselben Diskussionsthreads, in denen sie begonnen haben. Wenn sich der Kommentar auf die gesamte Pull-Anfrage oder auf mehrere Kommentare im selben Thread bezieht, zitieren Sie den kommentierten Kommentar. Um von einer E-Mail zu einem veralteten Diskussionsthread zu wechseln, verwenden Sie anstelle des Links "Auf GitHub anzeigen" den Link "In Pfad / zu / Datei".
- Wenn während des Überprüfungsprozesses Kardinalentscheidungen unter dem Gesichtspunkt von Kodierungsstandards oder anderen formalisierten Vereinbarungen getroffen werden, ist der Verfasser des Kodex verpflichtet, diese Entscheidungen in die entsprechenden Dokumente einzutragen.
- Bei der Überprüfung geht es nicht nur um den Code, sondern um die gesamte Aufgabe. Behandeln Sie die Anforderungen in der Aufgabe oder den Layouts nicht als die ultimative Wahrheit - jeder macht Fehler und niemand kann alle Nuancen berücksichtigen. Ein frisches Aussehen und vernünftige Vorschläge kommen nur dem Produkt zugute.
Überprüfungsprozess nach Code-Autor
- Die Aufgabe wurde erst abgeschlossen, nachdem die Überprüfung, das Testen und die Freigabe des "Produkts" bestanden wurden.
- Antworten Sie auf alle Kommentare des Rezensenten und lassen Sie Kommentare nicht unbeantwortet, unabhängig davon, ob Sie sie akzeptiert haben oder nicht.
- Denken Sie über die Fragen nach, die während der Überprüfung auftreten oder auftreten können. Möglicherweise fehlt im Codeabschnitt ein Kommentar, oder es ist besser, den Code expliziter zu schreiben.
- Korrigieren Sie vorhandene Commits nicht mit einem gend commit --amend, sondern nehmen Sie Änderungen als separate Commits vor, eines für jeden Fix. Das Korrigieren vorhandener Commits erschwert den Überprüfungsprozess erheblich, da Sie den gesamten Code erneut überprüfen müssen.
- Schreiben Sie nach dem Hinzufügen eines neuen Commits zur Pull-Anforderung in einem separaten Kommentar eine Zusammenfassung der Änderungen, damit die interessierten Parteien Bescheid wissen. Dies gilt sowohl für Korrekturen während der Überprüfung als auch für Korrekturen während des Tests.
- Schreiben Sie nach der Überprüfung vor dem Senden der Aufgabe zum Testen den Verlauf der Commits neu (git rebase --interactive), nehmen Sie Korrekturen an den einzelnen Commits vor und löschen Sie die temporären Commits. Aktivieren Sie die Option --autosquash, um den Vorgang zu vereinfachen.
Überprüfungsprozess durch Prüfer
- Wenn Sie zum Zeitpunkt der Überprüfung beschäftigt sind, teilen Sie mir genau mit, wann Sie mit der Überprüfung beginnen werden.
- Fordern Sie nicht, sondern schlagen Sie Änderungen vor.
- Kommentieren Sie den Code, nicht die Person, die ihn geschrieben hat.
- Sie übernehmen die Verantwortung für den geschriebenen Code und gehen entsprechend auf die Überprüfung ein. Dies bedeutet jedoch nicht, dass der Autor des Codes alle Ihre Anforderungen strikt erfüllen muss. Denken Sie daran, dass viele Dinge auf unterschiedliche Weise erledigt werden können.
- Befolgen Sie die Ziele der Überprüfung und schlagen Sie wesentliche Änderungen vor. Bestehen Sie nicht auf unkritischen Änderungen. Geben Sie in einem Kommentar an, wie wichtig Korrekturen sind.
- Wenn Sie ein ernstes Problem feststellen, unterbrechen Sie die Überprüfung und warten Sie, bis der Autor das Problem behoben hat. Höchstwahrscheinlich muss nach der Korrektur noch einmal überarbeitet werden.
- Achten Sie nicht nur darauf, was geändert wurde, sondern auch darauf, was nicht geändert wurde. Suchen Sie nach dem Code und zeigen Sie ihm den Code, der geändert werden sollte, aber nicht (vergessene Importe oder nicht verwendete Klassen, Verwendung von überarbeitetem Code an anderer Stelle usw.).
- Überprüfen Sie nach Änderungen durch den Code-Autor die Korrekturen und die gesamte Pull-Anforderung erneut. Vorbehaltlich von Korrekturen haben Sie möglicherweise neue Kommentare oder Fragen.
- Verschwenden Sie keine Zeit damit, Code zu überprüfen, der sich im Rahmen der Aufgabe nicht geändert hat. Die Zuordnung eines Codeteils zu einer Funktion wird als Änderung betrachtet. Die Codeübertragung „wie sie ist“ wird nicht als Änderung angesehen. Die Reform des Codes in der betroffenen Datei liegt im Ermessen des Autors.
- Der Prüfer bearbeitet den Code in der Verzweigung nicht unabhängig, weil er ihn so sehr oder einfacher haben möchte. Änderungen werden vom Autor des Codes vorgenommen.
- Wenn Sie eine Überarbeitung vorgenommen haben, versuchen Sie, nicht zu Lasten des Stroms zu verzögern oder zu anderen Aufgaben zu wechseln
Gebrauchte Materialien und verwandte Links
PS Teilen Sie Ihre Regeln, Empfehlungen und nützlichen Benutzerfälle zum Überprüfungsprozess in den Kommentaren mit