Początkowo tytuł tego artykułu miał brzmieć „rozmiar ma znaczenie”, ale na tyle mnie skręciło z żenady, że postanowiłem go zmienić. Gdybym miał opisać dobry Pull Request TYLKO jednym słowem, to odpowiedziałbym, że MAŁY. Gdyby to miałaby być jedyna rzecz, którą zapamiętasz z tego artykułu, to niech to będzie to. Zachęcam jednak, by przeczytać artykuł do końca, bo „rozmiar to nie wszystko” (przepraszam, musiałem).

Keep it small, stupid!

No dobra, ale jaki to jest mały Pull Request? Dla każdego ta odpowiedź będzie inna. Z pewnością nie definiowałbym tego liczbą linii kodu. Trafiłem ostatnio na artykuł, gdzie konkluzją było wskazanie idealnego rozmiaru Pull Requesta na 50 linii zmian, czy artykuł wskazujący, że statystycznie najlepiej sprawdzają się Pull Requesty, gdzie zmieniono trzy pliki lub mniej. Tylko problem ze statystykami jest taki, że jeśli ja jem na obiad mięso, a ty kapustę, to statystycznie jemy gołąbki.

Osobiście uważam, że wszelkie rekomendacje wskazujące konkretne liczby zmienionych plików czy linii są o kant dupy rozbić. W statystykach dotyczących Pull Requestów nie da się ująć moim zdaniem najważniejszego aspektu, który ma wpływ na czas i jakość code review, czyli złożoności zmian. Inaczej robi się code review prostego CRUD-a, inaczej skomplikowanej logiki, gdzie są do obsłużenia nieoczywiste przypadki i scenariusze, a jeszcze inaczej kodu spaghetti bez testów. Porównując takie dwie skrajności, Pull Request z 1000 linii zmian może okazać się prostszy w sprawdzeniu niż taki, który zmienionych linii ma np. 200. Podobnie w statystykach nie jest ujęte np. doświadczenie zespołu, technologia, obecna jakość kodu w projekcie i bambilion innych czynników.

Dla mnie mały Pull Request to taki, który jestem w stanie sprawdzić, zanim się zmęczę lub rozproszę. Zwykle mój organizm domaga się przerwy po około 25-30 minutach wytężonego wysiłku umysłowego. Jeśli w tym czasie jestem w stanie przeczytać kod i co najważniejsze zrozumieć go, to taki Pull Request jest dla mnie mały. Oczywiście dla każdego ta metryka będzie inna, ale o tym za chwilę.

W opisanym podejściu, do oszacowania czy Pull Request jest mały, przydatna może być metryka WTFs/Minute.

Na potrzeby tego artykułu naciągnąłbym tu nieco definicję WTF-a z „bubla w kodzie” na „fragment kodu, dla którego przeskanowanie wzrokiem nie wystarczy, by go zrozumieć”.

Czasami bez kilku takich WTF-ów w kodzie może być ciężko, ale im jest ich więcej w ramach jednego Pull Requesta, tym moim zdaniem trudniej o jakościowe code review. Kierowałbym się więc zasadą, że wraz ze wzrostem złożoności Pull Requesta jego rozmiar powinien maleć.

Dopasuj rozmiar Pull Requesta pod code reviewera

To, że coś u mnie działa w ten sposób nie znaczy, że u Ciebie też tak będzie. Kształt Pull Requesta według mnie powinien być dopasowywane pod osoby, które będą robić code review.

Jeśli code review będzie robił ktoś dobrze zaznajomiony z daną częścią systemu, większa paczka zmian pewnie będzie dla tej osoby mniej problematyczna niż dla osoby, która np. zaglądała tam raz lub dopiero się wdraża. Pisząc kod, warto podejść empatycznie do tematu i przygotować Pull Requesta tak, by jego sprawdzenie nie było problematyczne dla reszty zespołu. Wypychając opasłe kawałki kodu ze skomplikowaną logiką, nie tylko utrudniamy robotę innym, ale też sobie. Szansa, że ktoś znajdzie 15 minut na sprawdzenie naszych zmian jest znacznie większa, niż że wygospodaruje dla nas dwugodzinny slot, żeby przebić się przez tonę kodu.

Mniejszy Pull Request to też szansa na lepsze jakościowo code review. Jeśli miałbym obstawiać, to obstawiłbym, że w tym 15-minutowym code review powstanie więcej komentarzy i będą bardziej merytoryczne, niż przy tym dwugodzinnym. Sprawdzenie dużego kawałka kodu to problem na wielu płaszczyznach. Po pierwsze zajmuje dużo czasu. Długi czas code review oznacza większe zmęczenie. Większe zmęczenie obniża zdolność do wyłapywania istotnych mankamentów w kodzie i tak dalej…

Dodatkowo pokusa zrobienia code review na pół gwizdka w przypadku ogromnego Pull Requesta jest większa.

Single Responsibility Principle rulez!

SRP to moja ulubiona z reguł SOLID nie tylko w kontekście tworzenia konkretnych komponentów w kodzie. SRP z powodzeniem można stosować w tworzeniu Pull Requestów.

Dobry Pull Request to taki, który dotyka tylko jednego kontekstu. Powiedzmy, że dodajesz nowy endpoint do REST API. Po dodaniu endpointu i napisaniu testów postanowiłeś/aś zrefaktorować testy dla pozostałych endpointów. Ktoś mógłby powiedzieć, że to bardzo dobrze, bo postąpiono tu zgodnie z zasadą skauta:

zostaw obozowisko w stanie lepszym, niż je zastałeś/aś

Jednocześnie sprawia to, że faktyczny powód do wystawienia Pull Requesta ginie w gąszczu innych zmian. Zasada skauta jest super, ale stosując ją, należy zachować umiar i rozsądek. Chodzi tu o posprzątanie TWOJEGO obozowiska, a nie całego lasu. Szczególnie warto o tym pamiętać, dodając usprawnienia w testach, code stylach czy robiąc refaktoryzację przy okazji.

W sytuacji, gdy powstaje dodatkowy kontekst zmian, to nawet gdyby zasada skauta miałaby dotyczyć kilku linii, to i tak warto rozważyć wystawienie zmian w postaci osobnego Pull Requesta. Jedną z głównych zalet Gita jest możliwość śledzenia zmian i opisywania ich. Załóżmy, że znalazłeś/aś błąd w konfiguracji połączenia w kliencie bazy danych. Dorzuciłeś/aś zmiany do wcześniej wspomnianego Pull Requesta z dodaniem endpointa do REST API. Taka zmiana w historii będzie trudna do znalezienia w historii w przyszłości. Nawet jeśli ktoś znajdzie w jakim commicie wpadła dana zmiana, to szansa na to, że w commit message będzie wszystko wyjaśnione jest mała.

Aplikacje, podobnie jak ogry, mają warstwy

Może się tak zdarzyć, że trzymamy się jednego kontekstu… a Pull Request i tak wyjdzie duży. W takiej sytuacji zwykle dzielę klocki, które składają się na listę zmian w mniejsze, spójne bloki. Wracając do przykładu z dodaniem endpointu do REST API, załóżmy, że służy on do dodania nowego zasobu do bazy danych. Aplikacja składa się z trzech warstw:

• warstwa definiująca publiczny interfejs — definiuje kształt endpointa, odebranie danych wejściowych i zwrócenie odpowiedzi z API;
• warstwa logiki biznesowej — stworzenie z otrzymanych danych obiektu domenowego i wykonanie na nim jakiejś akcji;
• warstwa dostępu do danych — odpowiedzialna za zapis i odczyt z bazy danych.

W tym przypadku rozwiązaniem może być podział jednego dużego Pull Requesta dodającego zmiany we wszystkich trzech warstwach na trzy mniejsze z podziałem na warstwy.

Wtedy z kontekstu zmiany dotyczącej jednego feature-a powstają nam trzy konteksty — feature w ramach konkretnej warstwy aplikacji. Podział niekoniecznie musi przebiegać na poziomie warstw aplikacji. Najważniejsze jest to, by zmiany były podzielone w sposób spójny i logiczny. Można też do tematu podejść inaczej. Najpierw stworzyć szkielet zmian tzn. dodać niezbędne pliki i klasy dla każdej z warstw, a w drugim Pull Requeście zaimplementować w nich logikę i połączyć je ze sobą.

Innym przykładem do analizy podziału kodu na mniejsze kawałki może być formularz w apce frontendowej. Projektując duży formularz, ostylowany i oskryptowany również możesz podzielić go na kilka Pull Requestów:

• kod HTML — w code review można wtedy skupić się na semantyce użytych znaczników, implementacji wymagań czy treści takich jak etykiety, czy opisy;
• style — sprawdzenie poprawności implementacji designu formularza zgodnie z mockupami i analiza kodu CSS;
• kod JavaScript — analiza kodu, sprawdzenie poprawności i jakości kodu.

Sposób podziału zmian na Pull Requesty będzie mocno zależny od samych zmian i podobnie jak z idealnym rozmiarem Pull Requesta nie ma tu gotowego rozwiązania.

Changelog

Opis zmian jest według mnie równie istotny jak kod, który ląduje w repozytorium. Changelog powinien być opisem DLACZEGO coś zostało zrobione, a nie CO i JAK. Odpowiedzi na pytania CO i JAK można znaleźć w samym kodzie.

Changelog pisany jest dla:

• zespołu — by mieć dostęp do czytelnej historii zmian;
• code reviewerów — by wprowadzone zmiany były dla nich zrozumiałe;
• klientów — jeśli changelog jest publiczny;
• siebie z przyszłości — by w razie potrzeby móc przypomnieć sobie, dlaczego coś zostało dodane i dlaczego coś zostało zrobione w ten sposób, a nie inny.

Changelog może również służyć do zwalidowania przestrzegania SRP przy tworzeniu Pull Requestów. Jeśli potrzebujesz opisać więcej niż jedną rzecz (kontekst) w changelogu jest to sugestia, że być może warto podzielić Pull Requesta na kilka mniejszych.

Tworząc changelog, warto wziąć pod uwagę kilka aspektów:

• changelog powinien wyjaśniać powód zmian i czynniki mające wpływ na kształt przygotowanego rozwiązania;
• changelog powinien odpowiadać na ewentualne pytania, które mógłby zadać code reviewer;
• pisząc changelog warto być empatycznym i napisać go tak, by faktycznie był przydatny dla innych, a nie po prostu był;
• nie warto skupiać się na szczegółach implementacyjnych. To można sprawdzić w kodzie. Podobnie nie warto skupiać się na rzeczach typu code style, fixowanie reguł lintera itp.

Self code review

Załóżmy, że masz gotowego Pull Requesta, wszystko gra i tańczy, changelog napisany. To teraz zrób krok w tył i krytycznym okiem przeczytaj swój kod i changelog od deski do deski. Zanim oddasz komuś kod do sprawdzenia, pierwsze sprawdzenie zrób sam(a).

Wielokrotnie zdarzyło mi się na etapie self code review znajdywać błędy, przez które Pull Request leciał wręcz do kosza. Drobne poprawki w swoich Pull Requestach znajduję praktycznie za każdym razem. Zdecydowanie lepiej, gdy potencjalne problemy wyłapiesz ty, niż gdy znajdzie je ktoś inny.

Na tym etapie lubię również zostawiać komentarze w miejscach, w których mam wątpliwości, alternatywne rozwiązania lub chcę, by ktoś inny szczególnie wnikliwie je przeanalizował. Stanowi to uzupełnienie intencji przedstawionej w kodzie i changelogu, pokazuje mój punkt widzenia i stanowi dobre otwarcie do ewentualnej dyskusji.

Podsumowanie

Myślę, że ten artykuł mógłbym podsumować słowami:

Twórz takie Pull Requesty, jakie sam(a) chciał(a)byś sprawdzać.

Jestem ciekaw, jakie cechy według Ciebie powinien mieć dobry Pull Request. Daj o tym znać w komentarzu. Poniżej zostawiłem również kilka dodatkowych materiałów, które mogą Cię zainteresować.

Źródła i materiały dodatkowe

• The ideal PR is 50 lines long
• How to Write a Git Commit Message
• My favourite Git commit
• How large pull requests slow down development
• Google Developers – Writing a Good Pull Request
• How to Make a Perfect Pull Request
• GitHub Docs – Best practices for pull requests
• Nie programujesz (tylko) dla siebie
• Why Estimated Review Time Improves Pull Requests And Reduces Cycle Time
• 6 Best Practices to Manage Pull Request Creation and Feedback
• Dlaczego Warto Tworzyć Małe Pull Requesty?

Zaobserwuj mnie na LinkedIn!

LinkedIn jest głównym medium, poza blogiem, gdzie publikuję swoje przemyślenia. Zaobserwuj mój profil na LinkedIn, by być na bieżąco!
Zachęcam też do zaobserwowania devszczepaniak.pl na Facebooku, gdzie oprócz informacji o nowych artykułach publikuję linki do ciekawych treści.

Udostępnij wpis

Szukasz taniego i dobrego VPS? Skorzystaj z Mikrusa i przy zakupie odbierz dodatkowy miesiąc usługi za darmo!

📖 Koniecznie sprawdź ofertę księgarni Helion oferującej tysiące książek dla programistów w dobrych cenach! Kupując z tego linku, pomagasz w rozwoju bloga.

Chcesz docenić moją pracę? Postaw mi kawę!