Programista otwiera pull request, który dodaje funkcję obliczania rabatu do usługi płatności. Testy przechodzą pomyślnie, a różnica jest niewielka. Recenzent zatwierdza go w dwie minuty za pomocą „LGTM”. Trzy miesiące później członek zespołu musi zmienić tę samą funkcję i odkrywa, że łączy ona reguły cenowe, zaokrąglanie i dostęp do bazy danych w jednym miejscu. Nikt nie jest w stanie jednoznacznie określić, co jest dozwolone.
To przykładowy scenariusz, a nie udokumentowany incydent. Pokazuje on, jakie efekty przynosi wzajemna recenzja kodu, gdy jest ona traktowana jako proces uczenia się: recenzent potrafi dostrzec wiarygodną zmianę, wskazać problem, który jeszcze nie jest błędem, i wyjaśnić go w sposób, który umożliwi autorowi podjęcie działań.
Ten przewodnik jest przeznaczony dla liderów ds. wdrażania rozwiązań inżynieryjnych i menedżerów ds. inżynierii. Pokazuje, jak projektować ćwiczenia z przeglądu kodu które rozwijają tę umiejętność celowo, zamiast liczyć na to, że recenzenci podchwycą ją z kolejki. Obejmuje ona problem z wydajnością, luki do zdiagnozowania, sposób organizacji przygotowań i ćwiczeń, jeden przykładowy przykład oraz sposób sprawdzania, czy umiejętność ta jest przenoszona na rzeczywiste recenzje. Przed użyciem zleć inżynierom sprawdzenie każdego przypadku, wady i kryterium.
Czym są ćwiczenia z zakresu przeglądu kodu?
Ćwiczenia z przeglądu kodu to ustrukturyzowane zadania praktyczne, w których programista dokonuje przeglądu przygotowanej zmiany, wyjaśnia swoje odkrycia i ich znaczenie, a następnie otrzymuje informację zwrotną na temat jakości tego wyjaśnienia. Różnią się one od przeglądów, które zespół przeprowadza codziennie. Zmiana jest wybierana z wyprzedzeniem, problemy z nią związane są znane, a celem jest poprawa osoby dokonującej przeglądu, a nie jej wdrożenie.
Szybkie fakty
| Question | Krótka odpowiedź |
|---|---|
| Jakie jest zadanie? | Wyjaśnij ustalenia przeglądu i przekaż autorowi uwagi, na podstawie których będzie mógł podjąć działania. |
| Jaki jest Twój wynik? | Dokładność ustaleń i przydatność wyjaśnień. |
| Czy samo liczenie defektów wystarczy? | Nie. Recenzje dotyczą czegoś więcej niż tylko usterek, więc ćwiczenie, które nagradza tylko liczbę błędów, wyrabia zły nawyk. |
| Jakie jest zapotrzebowanie poznawcze? | Przeanalizuj i oceń projekt, a następnie stwórz lepszą propozycję. |
| Kto potwierdza tę sprawę? | Kierownik ds. inżynierii lub starszy inżynier, który jest właścicielem bazy kodu. |
| Czego ćwiczenia nie naprawią? | Czas na przegląd, niejasna własność i presja szybkiego połączenia. |
| Skąd wiesz, że zadziałało? | Nowa, niewidoczna zmiana sprawdzona pod kątem ustalonych kryteriów oraz kontynuacja rzeczywistych recenzji. |
1. Opisz problem z wydajnością
Zacznij od zadania, w jednym zdaniu: po wprowadzeniu zmiany recenzent wyjaśnia, co odkrył, dlaczego jest to ważne i co autor mógłby z tym zrobić. „Wyjaśnia” to ważne słowo. Zauważenie problemu to połowa sukcesu. Powiedzenie o tym tak, aby kolega o innym poglądzie mógł to zrozumieć, rozważyć i podjąć działanie, to druga połowa.
Badania nad nowoczesnym przeglądem kodu wskazują na wyjście poza wyszukiwanie błędów. W badaniu przeprowadzonym w firmie Microsoft, Bacchelli i Bird obserwowali, przeprowadzali wywiady i ankiety wśród programistów i menedżerów. Odkryli, że wyszukiwanie defektów nadal stanowiło główną motywację do przeglądu, ale przeglądy mniej koncentrowały się na defektach, niż oczekiwano. Przynosiły one również inne korzyści, takie jak dzielenie się wiedzą, świadomość zespołu i alternatywne rozwiązania. Badacze opisali zrozumienie kodu i zmian jako kluczowy aspekt przeglądu (Bacchelli i Bird, ICSE 2013). Jest to badanie zespołów jednej firmy, więc wykorzystaj je jako powód do zaprojektowania zespołu w sposób zrozumiały, a nie jako ocenę swojego zespołu.
Opublikowany standard Google dotyczący recenzji wskazuje na to samo. Nakazuje on recenzentom akceptować zmiany, jeśli zdecydowanie poprawiają one ogólną kondycję kodu, nawet jeśli nie jest on idealny, i stwierdza, że recenzja może nauczyć programistów czegoś nowego, dlatego komentarze, które pomagają komuś się uczyć, są mile widziane (Praktyki inżynieryjne GoogleOba źródła opisują przegląd jako miejsce, w którym dokonuje się oceny i ją przekazuje. To właśnie powinny być ćwiczenia, które ćwiczysz.
2. Zdiagnozuj luki w nauce i kontekście
Porównaj zadanie z tym, co Twój obecny program ćwiczy i ocenia.
- Czy obecna praktyka wykorzystuje rzeczywiste zadanie? Jeśli nowi recenzenci uczą się, czytając przewodnik stylistyczny, a następnie recenzując rzeczywiste pull requesty, ćwiczą na prawdziwej pracy, bez miejsca, w którym można się pomylić. Jeśli ocena jest quizem z etykiety recenzowania, mierzy ona znajomość zasad, a nie umiejętność ich zastosowania w przypadku zmiany.
- Jakie jest zapotrzebowanie poznawcze? W zrewidowanej taksonomii Blooma ocena trafności projektu i rozważenie jego kompromisów odbywa się na poziomie analizy i oceny, a proponowanie lepszej struktury sięga poziomu tworzenia. Jeśli w ćwiczeniach zadajesz tylko pytanie „co robi ten kod?”, kończą się na zrozumieniu. Nasz przewodnik po dopasowywanie działań edukacyjnych do taksonomii Blooma pokazuje jak dopasować aktywność do poziomu.
- Czy coś innego niż umiejętności stoi na przeszkodzie? Sprawdź czas recenzji, narzędzia, odpowiedzialność i normy zespołu. Jeśli recenzenci mają pięć minut na każde żądanie ściągnięcia, żadne ćwiczenie nie przyniesie przemyślanego wyjaśnienia. Jeśli autorzy traktują każdy komentarz jako krytykę, recenzenci będą łagodzić swoje ustalenia, aż w końcu nic nie powiedzą. Zgłoś te przyczyny osobom, które mogą je rozwiązać.
3. Przygotowanie projektu, praktyka i opinia zwrotna
Przypisz każdemu etapowi osobne zadanie.
Przygotowanie. Sprawdź, czego potrzebują recenzenci przed rozpoczęciem: listy kontrolnej zespołu ds. przeglądu, zasad projektowania, na których się opiera, oraz sposobu odczytywania różnic w narzędziach. Zadbaj o to, aby proces był krótki i dostosowany do tempa pracy. Kontrola zgodności (ang. recall check) potwierdza jedynie spełnienie wymagań wstępnych i nie stanowi dowodu na to, że ktoś może dokonać przeglądu.
Ćwiczyć. Używaj przygotowanych zmian z niewielką liczbą zasianych obaw różnego rodzaju: błąd poprawności, problem z utrzymaniem, taki jak pomieszanie odpowiedzialności w przykładzie otwierającym, niejasna nazwa lub brak testu, oraz fragment kodu, który jest poprawny. Poproś recenzenta o napisanie komentarza, który by zostawił, uszeregowanie obaw i wskazanie dodatkowych informacji, których by potrzebował. Praktyczna lekcja CodeRefinery pokazuje, jak to wygląda: użytkownicy otwierają pull request zawierający drobną literówkę i większy błąd, a następnie recenzują go jako równy recenzent (CodeRefinery, Praktykowanie przeglądu kodu). Twórz swoje projekty w oparciu o własną bazę kodu, aby konwencje i kompromisy były realne.
Informacje zwrotne. Powiąż to z decyzjami podjętymi przez recenzenta. „Zauważyłeś problem z zaokrąglaniem, ale w swoim komentarzu napisałeś, że „to wygląda źle”, nie podając, które dane wejściowe to psują” jest bardziej przydatne niż „znaleziono 2 z 4”.
Dane wejściowe na żywo czy przegląd asynchroniczny? Wprowadzanie zmian na żywo przynosi największą wartość, gdy problem jest niejednoznaczny, a recenzenci uczą się, słysząc, dlaczego starszy inżynier miałby go zgłosić, lub go odrzucić. Asynchroniczna recenzja wystarcza do porównania komentarzy z opatrzoną komentarzem recenzją ekspercką.
4. Omów realistyczny przykład
Ilustrujące. Kierownik ds. inżynierii powinien zweryfikować przypadek i kryteria odpowiedzi przed ich użyciem.
Walizka. Zmiana dodaje kalkulację rabatu do usługi płatności. Przechodzi ona pomyślnie testy. W jednej funkcji stosuje rabaty procentowe i stałe, zaokrągla wynik, zapisuje do bazy danych i wysyła zdarzenie. Ma jeden test – dla pojedynczego rabatu procentowego.
Zadanie. Recenzent pisze komentarze, które chciałby zostawić, klasyfikuje swoje zastrzeżenia i mówi, co chciałby wiedzieć przed zatwierdzeniem.
Pierwsza próba. „Wygląda dobrze, test przechodzi. Może go podzielić?” Recenzent zauważył coś, ale nie wyjaśnił, co, dlaczego to jest ważne ani co zrobić. Autor nie może podjąć żadnych działań.
Prześlij opinię i spróbuj ponownie. Facylitator pyta: co mogłoby spowodować awarię tej funkcji w przyszłości? O co poprosiłbyś autora przed zatwierdzeniem? Ponowna próba wymaga szczegółowego komentarza do każdego problemu, wraz z uzasadnieniem i sugestią.
Silniejsza próba. Funkcja stosuje dwa rodzaje rabatu: zaokrągla, zapisuje i publikuje zdarzenie, więc zmiana zaokrąglania mogłaby zmienić to, co przechowujemy i co publikujemy jednocześnie. Poprosiłbym o przeniesienie reguł cenowych do czystej funkcji, którą moglibyśmy testować samodzielnie. Pojedynczy test obejmuje tylko rabat procentowy. Poprosiłbym o stały rabat i zamówienie, które sprowadza sumę do zera. Nie jestem pewien, czy zdarzenie ma być uruchamiane, gdy suma będzie zerowa, więc zapytałbym autora. Zauważ, że ten komentarz opisuje problem, podaje przyczynę, przedstawia konkretną sugestię i wyjaśnia, czego recenzent nie wie.
5. Ocena zdolności i zaplanowanie przeniesienia
Dowodem na zdolność jest wykonanie nowej zmiany, której recenzent nie widział. Oceń dokładność ustaleń i użyteczność wyjaśnienia. Prosta rubryka wykorzystuje skalę od 0 do 2 dla każdego kryterium:
| Kryterium | Obserwowalne dowody |
|---|---|
| Wykonanie zadania | Wyszukuje istotne kwestie dotyczące zmiany i rejestruje dowody dla każdej z nich. |
| Rozumowanie | Wyjaśnia, dlaczego każda obawa jest ważna, proponuje alternatywę i mówi o tym, co pozostaje niepewne. |
| Granice | Przestrzega zasad zespołu dotyczących przeglądu i prosi o pomoc lub informacje, gdy brakuje autorytetu lub kontekstu. |
Kotwice: 0 oznacza brak lub brak wsparcia, 1 oznacza częściowe z istotnymi pominięciami, a 2 oznacza kompletne i uzasadnione zgodnie z uzgodnionymi kryteriami. Zdefiniuj błędy krytyczne osobno, na przykład zatwierdzenie zmiany z ryzykiem utraty danych, aby dobry wynik ogólny nie mógł ich ukryć. Dostosuj kryteria z kierownikiem ds. inżynierii; ta rubryka stanowi propozycję wyjściową, a nie sprawdzony standard gotowości. Więcej informacji na temat uzasadnienia punktacji można znaleźć w naszym przewodniku. projektowanie interaktywnej praktyki z użyteczną informacją zwrotną.
Zaplanuj transfer. Po ćwiczeniu sprawdź próbkę rzeczywistych recenzji recenzenta kilka tygodni później, stosując te same kryteria. Porównaj z danymi bazowymi sprzed szkolenia i z góry określ populację oraz harmonogram. Przed zaliczeniem ćwiczeń sprawdź inne zmiany, które zaszły w tym samym okresie, takie jak nowe narzędzie do recenzji lub zmiana personelu.
6. Przeprowadź ćwiczenie na żywo lub we własnym tempie dzięki AhaSlides
Możesz przeprowadzić ćwiczenie w ramach warsztatów lub pozwolić recenzentom samodzielnie je przepracować. Podczas sesji na żywo pokaż przygotowaną zmianę i wykorzystaj interaktywne slajdy do dyskusji:
- Wybierz odpowiedź na pytanie „Którą obawę podniósłbyś jako pierwszą?”, z obawami zasianymi jako opcjami. Pokaż spread, zanim ujawnisz swój ranking.
- Otwarty „Napisz komentarz, który chcesz zostawić”. Recenzenci mogą porównywać swoje sformułowania z innymi, co pokazuje umiejętność wyjaśniania.
- Skala ocen „jak poważne to jest?”, aby grupa mogła zobaczyć, gdzie oceny się różnią i omówić ich przyczyny.
Recenzenci, którzy nie mogą uczestniczyć w sesji, mogą skorzystać z tej samej sekwencji, w której tempo pracy będzie dostosowane do ich potrzeb, a po każdej odpowiedzi będzie wyświetlana recenzja eksperta z adnotacjami. Wszelkie twierdzenia dotyczące wykonywania kodu, integracji lub funkcji AI należy traktować jako niepotwierdzone, dopóki nie zostaną sprawdzone na własnych materiałach.
Jeśli szkolisz również recenzentów w zakresie kodu napisanego przez sztuczną inteligencję, zapoznaj się z naszym towarzyszącym przewodnikiem Szkolenie z przeglądu kodu generowanego przez sztuczną inteligencjęTen post dotyczy audytu generowanych wyników. Ten dotyczy tego, jak ludzie wzajemnie oceniają swoją pracę i jak wyjaśniają swoje odkrycia.
Ograniczenia, które mogą pozostać
- Czas na recenzję. Przemyślany komentarz wymaga więcej czasu niż „LGTM”, a terminy zbliżają się do wersji skróconej.
- Normy zespołowe. Jeśli opinia zostanie potraktowana jako osobista krytyka, recenzenci złagodzą swoje wnioski lub je wycofają.
- Relacja ze sprawy. Jedno z ćwiczeń pokazuje kilka rodzajów obaw. Ocena nie opisuje ogólnej oceny recenzenta.
- Transfer. Jakość usług w warsztacie nie jest taka sama, jak jakość usług w pełnej kolejce, dlatego sprawdź także prawdziwe opinie.
Zgłosić je sponsorom z wyprzedzeniem i zaplanować osobne poprawki. Ćwiczenia poprawiają to, co recenzent może zobaczyć i wyjaśnić. Nie wyznaczają one czasu ani norm.
PYTANIA I ODPOWIEDZI
Czym są ćwiczenia z zakresu przeglądu kodu?
Są to przygotowane zadania praktyczne, w których programista weryfikuje zmianę pod kątem znanych zastrzeżeń, zapisuje komentarze, które chciałby zostawić, i otrzymuje informację zwrotną na temat dokładności i przydatności. Celem jest rozwijanie umiejętności recenzenta, a nie wprowadzanie zmian.
Jak oceniasz, czy ocena recenzenta uległa poprawie?
Wprowadź nową zmianę, której nie widzieli, i oceń wyniki oraz wyjaśnienie w oparciu o ustalone kryteria. Następnie sprawdź próbkę prawdziwych recenzji kilka tygodni później. Quiz z zasad recenzji potwierdza jedynie spełnienie wymagań wstępnych.
Czy recenzja kodu przez ekspertów służy głównie wyszukiwaniu błędów?
Wykrywanie defektów nadal stanowi główną motywację, ale jedno z badań przeprowadzonych w firmie Microsoft wykazało, że recenzje mniej skupiały się na defektach niż oczekiwano, a jednocześnie zapewniały dzielenie się wiedzą i zwiększały świadomość zespołu. Projektuj ćwiczenia, które nagradzają wyjaśnienia i zrozumienie, a także liczbę defektów.
Gdzie zacząć
Wybierz jeden rodzaj zmiany, który Twój zespół często analizuje. Napisz raport o wynikach, poproś starszego inżyniera o przygotowanie jednej zmiany z trzema lub czterema problemami, które mogą być istotne, i stwórz trzy kryterialną rubrykę z oceną od 0 do 2 oraz listą błędów krytycznych. Przeprowadź pilotaż z małą grupą, a następnie porównaj kolejne rzeczywiste analizy z poziomem bazowym.
Aby zobaczyć, jak ćwiczenie przeglądowe można przeprowadzić na żywo z udziałem własnego zespołu, a następnie wykorzystać je w indywidualnym tempie, zapoznaj się z AhaSlides.
