Poradnik Recenzenta

Updated 1,818 Days AgoPublic

Actions

Opis tego, jak wygląda proces recenzji kodu. Na co zwracać uwagę i jak sugerować zmiany?

Proces

Sprawdź kolejno następujące poniżej rzeczy. Postaraj się znaleźć jak najwięcej komentarzy i następnie zrób odpowiednio "Request changes" jeżeli rewizja wymaga zmian lub "accept", jeżeli wszystko jest OK.

⚠ Przy pisaniu komentarzy stosuj się do Standardów komentarzy do diffów.

1. Sprawdzenie metadanych

Sprawdź, czy metadane rewizji spełniają każdy z punktów dotyczących ich standardów. Jeżeli jakichś informacji brakuje lub jakieś informacje są nieprawidłowe, popraw je samodzielnie. Jeżeli samodzielna korekta metadanych w danym przypadku niemożliwa, bo brakuje Ci jakichś informacji, to zgłoś to w odpowiednim komentarzu.

Brakujące lub błędne metadane wystarczają do tego, aby zmienić status rewizji na request changes, jednak wciąż trzeba sprawdzić pozostałą część rewizji.

2. Treść taska

Przeczytaj treść taska/tasków podpiętych do danej rewizji. Zwróć uwagę, czy w komentarzach do taska zostały dokonane jakieś ustalenia i miej je w pamięci czytając kod rewizji.

3. Test

Wykonaj instrukcje opisane w Test Planie. Czy wszystko wykonuje się poprawnie? Jeżeli nie, to zaznacz to w komentarzu do całego diffa. Być może jesteś w stanie określić, która linijka którego pliku odpowiada za niepoprawne działanie kodu? Jeżeli tak, to napisz o swoich podejrzeniach w komentarzu. Załącz wszelkie stosy błędów lub screenshoty, które mogą być pomocne autorowi/autorce taska.

4. Lista plików

Sprawdź listę plików, które zostały utworzone/zmienione w tej rewizji. Możesz wcisnąć F w widoku diffa, aby schować/pokazać pasek boczny z listą plików dotkniętych daną rewizją. Czy mają poprawne nazwy? Czy są w odpowiednich katalogach? Pamiętaj, że nazwy plików powinny czytelnie wskazywać na to, co się w danym pliku znajduje. Pliki powiązane ze sobą (np. odpowiedzialne za ten sam komponent) powinny znajdować się w osobnym, wspólnym katalogu.

Czy być może któreś pliki nie są używane? Czasem różne pliki tymczasowe dostają się do kodu rewizji. Czasem można je zidentyfikować patrząc na samą listę plików, ale czasem to wychodzi dopiero po przeczytaniu kodu.

5. Kod

Przeczytaj uważnie kod rewizji.

Kod powinien być zrozumiały. Jeżeli jakiś fragment kodu jest dla ciebie niezrozumiały, to zgłoś to w komentarzu, prosząc o wytłumaczenie jego działania. Postaraj się współpracować z autorem/autorką rewizji w znajdowaniu rozwiązania tego problemu. Oto lista potencjalnych rozwiązań problemu nieczytelności kodu, w kolejności od najbardziej do najmniej preferowanych:

1. Przepisanie kodu na bardziej deklaratywny (zob. Standardy kodu, 1.3)
2. Zmiana nazw funkcji/metod/zmiennych tak, aby były bardziej zrozumiałe (np. zamiast i, j, n - bardziej opisowe nazwy, jak item, iterator, count, itp)
3. Dodanie komentarza inline wyjaśniającego działanie kodu
4. Dodanie dokumentacji tego kodu w osobnym pliku

Komentując kod możesz zaznaczyć konkretną linijkę, klikając na jej numer - wtedy komentarz będzie dotyczył tej konkretnej linijki. Możesz też zaznaczyć wiele linijek jednocześnie, aby zaznaczyć ich większą ilość.

Standardy kodu

Zapoznaj się z treścią Standardów Kodu w Sealcode:

https://hub.sealcode.org/w/sealhub_workflow/standardy/

sprawdź każdą linijkę zmian w rewizji pod względem zgodności ze standardami. Na początku będzie się to wydawało upierdliwe, ale z czasem zaczniesz intuicyjnie wyłapywać pewne niedoskonałości w kodzie.

6. Czy nic nie zostało pominięte?

Zdarzają się taski polegające np. na migracji wszystkich miejsc w kodzie z rozwiązania A na rozwiązanie B. Trzeba wtedy starannie sprawdzić, czy na pewno wszystkie miejsca w których było użyte A zostały zastąpione B. Można to zrobić za pomocą komendy [ag](https://github.com/ggreer/the_silver_searcher), szukając w ten sposób wszystkich wystąpień jakiegoś fragmentu z A w całym projekcie. Jeżeli zostaną jakieś nieprzemigrowane fragmenty, trzeba umieścić stosowny komentarz i zrobić "request changes"

7. Ponowne review

Gdy autor rewizji wyśle do niej nowego diffa, sprawdź ponownie każdy zmieniony fragment kodu. Upewnij się, że autor rewizji ustosunkował się do każdego z Twoich komentarzy.

Zapoznaj się z wersjami w panelu "History":

Jeżeli w miedzyczasie autor wrzucał kilka nowych wersji, możesz dodać do adresu diffa /new - wtedy wyświetli się porównanie najnowszej wersji rewizji z tą wersją, która była aktualna ostatnim razem, kiedy wykonywałeś/aś jakąś akcję w tej rewizji:

https://hub.sealcode.org/D123/new/