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. wsparcia inżynieryjnego i menedżerów ds. inżynierii. Pokazuje, jak projektować ćwiczenia z przeglądu kodu , które celowo rozwijają tę umiejętność, zamiast oczekiwać, że recenzenci przejmą ją z kolejki. Obejmuje on 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 przeglądy. Przed użyciem należy zlecić inżynierom sprawdzenie każdego przypadku, błędu 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, a 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 należy je traktować jako powód projektowania pod kątem zrozumienia, a nie jako wskaźnik dla 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ą w nauce, są mile widziane ( Google Engineering Practices ). Oba źródła opisują recenzję jako miejsce, w którym dokonuje się oceny i przekazuje ją dalej. Właśnie to 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 przeglądu zespołu, 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 potwierdza jedynie spełnienie wymagań wstępnych i nie stanowi dowodu na to, że ktoś może dokonać przeglądu.
Ćwicz. 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 z równym ( CodeRefinery, Practicing code review ). Twórz własne zmiany na podstawie własnej bazy kodu, aby konwencje i kompromisy były realne.
Informacja zwrotna. Powiąż ją 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”.
Wprowadzanie danych na żywo czy asynchroniczna recenzja? Wprowadzanie danych 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 wystarczy, aby porównać komentarze 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.
Przypadek. 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 powinien wiedzieć przed zatwierdzeniem.
Pierwsza próba. „Wygląda dobrze, test przechodzi. Może go podzielić?” Recenzent coś zauważył, ale nie wyjaśnił, co, dlaczego to ważne ani co zrobić. Autor nie może podjąć żadnych działań.
Informacja zwrotna i ponowna próba. Facylitator pyta: jaka przyszła zmiana w tej funkcji mogłaby spowodować awarię? O co poprosiłbyś autora przed zatwierdzeniem? Ponowna próba wymaga szczegółowego komentarza do każdego problemu, wraz z uzasadnieniem i sugestią.
Mocniejsza 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 wynosi zero, więc zapytałbym autora”. Zauważ, że ten komentarz opisuje problem, podaje przyczynę, przedstawia konkretną sugestię i stwierdza, 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 wiążącej się 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 punktacji uzasadnienia można znaleźć w naszym przewodniku po projektowaniu praktyk interaktywnych 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 poradnikiem dotyczącym szkoleń z zakresu przeglądu kodu generowanego przez sztuczną inteligencję . Ten wpis dotyczy audytu wygenerowanych wyników. Ten dotyczy tego, jak ludzie recenzują swoją pracę i jak wyjaśniają swoje spostrzeżenia.
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.
