Najlepsze praktyki przeglądu kodu

Autor korzyści z uzyskania innego spojrzenia na swoje zadania i kod. Często uczą się nowych sztuczek lub odkrywają potencjalnie bardziej optymalny sposób rozwiązania określonego problemu. Będą również wdrażać swój zestaw zmian pewnie, wiedząc, że inne osoby sprawdziły kod pod kątem poprawności i zgodziły się, że wszystko jest w porządku.

Recenzent Korzyści z obserwowania różnych podejść do rozwiązywania problemów w działaniu. Poprawią również swoje umiejętności czytania kodu, co jest bardzo ważne, gdy zagłębiają się np. w bibliotekę ocenianą pod kątem wykorzystania w projekt. Recenzja kodu jest również okazją do nauki zarówno dla recenzenta, jak i autora: mogą oni również nauczyć się nowych sztuczek.

The zespół Zyskuje na tym cały zespół, ponieważ sprawdzenie rozwiązania danego problemu wymaga zrozumienia go przynajmniej na wysokim poziomie abstrakcji. Pomaga to zlikwidować wszelkie przypadkowe silosy wiedzy, które mogą pojawić się w zespole. Zwiększy to również "współczynnik autobusu": ponieważ co najmniej dwie osoby (najlepiej więcej) są świadome danej zmiany, istnieje mniejsze prawdopodobieństwo sytuacji, w której nikt w zespole nie wie, jak zaktualizować moduł lub dlaczego może wystąpić określony błąd.

Klient czerpie korzyści z szybko i pewnie wdrażanych zmian i rozwiązań. Wraz z innymi najlepszymi praktykami (takimi jak doskonałe pokrycie testami, CI/CD, środowiska przejściowe itp.) przeglądy kodu zapewniają również, że wdrażane rozwiązania są bezpieczne, rozsądne i spełniają określone wymagania.

Cel i zastosowanie niniejszych wytycznych

Należy pamiętać, że przede wszystkim sugestie te mają na celu stworzenie środowiska sprzyjającego ambitnemu i skutecznemu rozwiązywaniu problemów, przy jednoczesnym tworzeniu siatki bezpieczeństwa i promowaniu zaufania i przejrzystości u każdego członka zespołu.

Chociaż zdecydowanie sugeruje się, aby zespół przestrzegał tych wytycznych, nie mają one być twardymi i szybkimi zasadami. Ramy te nie są również przeznaczone jako "proces", którego należy dokładnie przestrzegać, ponieważ sztywne procesy mają tendencję do zmniejszania szybkości i promowania marnotrawstwa.

Zachęcamy do korzystania z tych wytycznych w swoim zespole. Pamiętaj jednak, że gdy programiści będą zmieniać zespoły, będą oczekiwać, że przegląd kodu w każdym zespole, do którego dołączą, będzie nadal oparty na tym dokumencie. Zachowaj wszelkie dodatkowe zasady udokumentowane i wnieś do tego dokumentu ulepszenia, które sprawdziły się wyjątkowo dobrze.

Obowiązki związane z przeglądem kodu

Każdy członek zespołu ma określone obowiązki w zakresie przeglądu kodu. Poniżej przedstawiono pewne zalecenia i zakazy dotyczące przeglądu kodu w zależności od roli w procesie.

Lider projektu

• DO upewnić się, że repozytoria są dobrze skonfigurowane (np. scalenia do gałęzi produkcyjnej nie są dozwolone bez co najmniej jednej zatwierdzającej recenzji).
• DO Upewnij się, że Twój zespół rozumie i stosuje te praktyki oraz aktywnie pracuje nad promowaniem zrozumienia, dlaczego robimy rzeczy w określony sposób.
• DO zwracaj uwagę na sytuacje, w których nie można rozstrzygnąć przeciwstawnych opinii: jako lider techniczny swojego zespołu jesteś odpowiedzialny za wybór bardziej odpowiedniego rozwiązania w takich przypadkach i utrzymanie postępu prac.
• Jednakże, NIE używać kierownictwa projektu jako tępego narzędzia. NIE "pull rank". DO Zachęcamy do recenzowania i krytykowania swoich rozwiązań, tak samo jak zachęcamy do krytykowania czyjejkolwiek pracy.
• Rozważ dodanie integracji z GitHub do kanału Slack swojego zespołu. Może to być pomocne w lepszym umieszczaniu próśb o recenzję na radarach recenzentów, ale w zależności od ogólnego wolumenu na kanale może to być odpowiednie dla twojego zespołu.

Członek zespołu

• Bierz udział w przeglądach kodu. Niedopuszczalne jest nieprzeglądanie kodu.
• Pamiętaj, by robić przeglądy kodu: twoi koledzy z zespołu polegają na tobie, jeśli chodzi o postępy w ich pracy!
• Jeśli absolutnie nie możesz wykonać określonej recenzji, DO komunikować to w sposób jasny i otwarty.
• Jednakże, NIE zakładać, że nie możesz wykonać określonego przeglądu, ponieważ nie znasz tego modułu/części systemu/specyfikacji logiki biznesowej. Przegląd kodu jest ważną okazją do nauki.
• Jeśli czujesz, że nie wiesz wystarczająco dużo o czymś, aby napisać recenzję, DO Zapytaj o to autora: z przyjemnością wyjaśni, na czym polegają wprowadzone zmiany.
• NIE odrzucanie recenzji na podstawie poziomu doświadczenia (Twojego lub autora).
• DO staraj się recenzować co najmniej tyle PR-ów, ile tworzysz. Najlepiej utrzymywać stosunek liczby recenzji do liczby wymaganych recenzji powyżej 1 (zwłaszcza w większych zespołach).

Autor

• DO zrozumieć, że to na tobie spoczywa odpowiedzialność za weryfikację kodu - twój zespół może proaktywnie szukać pull requestów do weryfikacji, ale nie musi tego robić.
• NIE zawsze przydzielaj/żądaj recenzji od tych samych członków zespołu - odniesiesz więcej korzyści z różnorodnej puli recenzentów (i odwrotnie, szersze grono programistów odniesie korzyści z recenzowania twojego kodu)
• NIE wykluczyć kogoś z przeglądu na podstawie doświadczenia. Młodsi programiści czerpią korzyści z recenzowania kodu. Starsi programiści czerpią korzyści z recenzowania kodu. Jak stwierdzono we wstępie do tego dokumentu, każdy korzyści z przeglądu kodu.
• ROZWAŻYĆ użycie randomizera do wyboru recenzentów. Np. w Ruby, %w[teammate1 teammate2 teammate3].sample może zdziałać cuda.
• DO Przypisuj co najmniej dwóch recenzentów do swoich pull requestów, chyba że jest to absolutnie niemożliwe. W ten sposób więcej osób skorzysta z procesu (a przy trzech osobach trudniej będzie osiągnąć remis).
• DO Bądź responsywny w swoich pull requestach. Chociaż nie powinieneś przerywać swojego przepływu, aby odpowiedzieć natychmiast na wszelkie komentarze, upewnij się, że Twoje odpowiedzi są terminowe - w przeciwnym razie Twoje PR będą zalegać w przeglądzie kodu w nieskończoność.
• DO przyjąć otwartą postawę. Zawsze zakładaj, że recenzent stara się pomóc, mając jak najlepsze intencje. Wyjaśnij swoją logikę, odnieś się do argumentów recenzenta i odpowiedz na jego pytania.
• DO Bądź uprzejmy. Nieporozumienia się zdarzają, ale nie muszą wymykać się spod kontroli i szkodzić atmosferze w zespole.
• DO Bądź szczery. Jeśli uważasz, że jest to najlepsze rozwiązanie, powiedz to i przedstaw swoje argumenty. Jeśli jesteś przekonany, że sugestie recenzenta są lepsze niż to, co stworzyłeś, powiedz mu o tym. Jeśli uważasz, że można stworzyć rozwiązanie "najlepsze z obu światów", wykorzystujące zarówno pomysły Twoje, jak i Twojego recenzenta, zaproponuj mu je. Ostatecznie należy dążyć do osiągnięcia konsensusu w pull requestach.
• DO Pozostaw rozwiązanie ich komentarzy swojemu recenzentowi - nie rozwiązuj ich tylko dlatego, że jesteś przekonany, że teraz jest w porządku.
• DO aktywnie wyjaśniaj recenzentom swoje zadanie, tok rozumowania i inne wymagania. W porządku jest nie wiedzieć - niedopuszczalne jest ukrywanie wiedzy.
• NIE Załóżmy, że wiesz wszystko - wszyscy jesteśmy niesamowitymi specjalistami, ale ważne jest, aby wnieść pewną pokorę do pracy z tobą.
• DO Bądź pierwszym recenzentem swojego kodu. Załóż kapelusz recenzenta i dokładnie przeskanuj kod, tak jak zrobiłbyś to w przypadku osoby, której nie lubisz najbardziej. Zidentyfikuj i wyeliminuj najbardziej oczywiste rzeczy, takie jak puste linie, wszelkie pozostałości lub brakujące specyfikacje. Nie pomijaj niczego - najprawdopodobniej i tak zostanie to wskazane. Nie marnuj czasu recenzentów!
• DO dokładnie opisz swój pull request. Opis jest dobry, gdy recenzent nie będzie niczym zaskoczony podczas czytania kodu. Pamiętaj, że nie może on czytać w twoich myślach. Dlatego ważne jest, aby opisywać rzeczy nieoczywiste, kluczowe decyzje wraz z uzasadnieniem lub wszystkie nowe klasy i pliki.
• ROZWAŻYĆ przy użyciu szablonu pull request. Jeśli korzystasz z Githuba, dodaj go do swojego repozytorium w sekcji .github/pull_request_template.md. Zachęca to wszystkich członków zespołu do opisywania swoich pull requestów. Jest to również o wiele łatwiejsze do napisania, gdy pole opisu jest wypełnione szablonem. Tutaj możesz znaleźć szablon, którego używamy w jednym z naszych projektów https://gist.github.com/weemanjz/a20ccb9f3f492b9bd21ab026a1d46353

Autor

• DO rozumieją, że to na nich spoczywa odpowiedzialność za przegląd kodu - Twój zespół może aktywnie szukać pull requestów do przejrzenia, ale nie musi tego robić.
• NIE zawsze przydzielać/żądać recenzji od tego samego recenzenci kodu - Będziesz czerpać więcej korzyści z różnorodnej puli recenzentów (i odwrotnie, szerszy zakres programistów skorzysta na recenzowaniu twojego kodu).
• NIE wykluczyć kogoś z przeglądu na podstawie doświadczenia. Młodsi programiści czerpią korzyści z wykonywania recenzje kodu. Starsi programiści czerpią korzyści z wykonywania recenzje kodu. Jak stwierdzono we wstępie do niniejszego dokumentu, każdy korzyści z wykonywania recenzje kodu.

Recenzent

• DO używać języka sugestii zamiast wymagań. Zamiast mówić "Powinieneś poprawić jakość kodu robiąc zamiast tego X"powiedzieć "Czy rozważałeś ulepszenie jakość kodu robiąc X?"
• DO wyjaśnić swoje sugestie. "Myślę, że X jest tutaj lepszy, ponieważ pomaga w transfer wiedzy i poprawa jakości kodu."
• Nawet jeśli sugestia pochodzi z obiektywnych źródeł (np. styl kodu wytyczne), DO poprosić autora o zrobienie czegoś, zamiast kazać mu coś zrobić. "Wszystkie widżety powinny być frobnicowane zgodnie z naszymi styl kodu przewodnik - [link]"
• NIE zakładać, że wiesz wszystko. "Rozumiem, że ten widget nigdy nie powinien się frobnicować, a w tych warunkach będzie - czy jest to wyjątek, który wymaga przegląd kodu?"
• DO używać inkluzywnego języka. "Wierzę, że byłoby nam lepiej w przyszłości, gdybyśmy zbudowali to w ten sposób. Co o tym sądzisz? lepszy przegląd kodu sugestia?" i "Może zamiast tego powinniśmy użyć tutaj X. skuteczny przegląd kodu?"
• DO Bądź szybki w wykonywaniu swoich recenzje kodu. Nie powinieneś przerywać swojego flow, aby je wykonać, ale staraj się, aby pętla była ciasna, jeśli to w ogóle możliwe. Niektórzy ludzie lubią wykonywać je na początku lub na końcu dnia pracy, jako "rozgrzewkę" lub "ochłonięcie".

Należy pamiętać, że te słowa kluczowe zostały wstawione w taki sposób, aby zachować nienaruszony kontekst i spójność tekstu. Jeśli chcesz, aby znalazły się one w określonych miejscach, prosimy o ich wskazanie.