Jaki jest najlepszy sposób na komentarz w recenzji kodu?

Mój zespół właśnie zaczął używać tygla / rybiego oka do inicjowania recenzji kodu za każdym razem, gdy jedno z nas coś sprawdza. Jest nas tylko 3 i każdy z nas jest zachęcany do przejrzenia kodu i pozostawienia komentarzy, które uznamy za stosowne.

Moje pytanie brzmi: jak najlepiej zostawić komentarz w wierszu kodu, z którym widzę problem? Chcę przekazać swój punkt widzenia, nie będąc szorstkim.

Nie chcę wyglądać, jakbym był na wysokim koniu i mówić: „ Robię to w ten sposób ... a także nie chcę wyglądać, jakbym chciał być autorytatywny i powiedzieć coś w stylu „ Należy to zrobić w ten sposób ... ”, ale wciąż muszę zrozumieć, że to, co robią, nie jest zbyt dobre.

Wyjaśnienie: To jest naprawdę dobry zasób do tego , co powinienem skomentować: czy przegląd kodu jest subiektywny czy obiektywny (kwantyfikowalny)? , ale szukam sposobu na skomentowanie tego.

Cóż, mam tendencję do komentowania w kilku ogólnych obszarach i każdy typ może być traktowany inaczej.

Wymagane zmiany Są to rodzaje zmian, w których wskazuję, że kod nie spełnia wymagań funkcjonalnych lub nie działa i musi zostać naprawiony przed przekazaniem go do produkcji. W tych komentarzach staram się być bardzo bezpośredni. Wymagania mówią ..., to nie robi tego. Lub to się nie powiedzie, jeśli wysłana wartość ma wartość NULL (szczególnie, gdy wiesz, że przypadek wystąpi na podstawie danych, które zostaną wysłane).

Są też słowa „to działa, ale tutaj jest lepszy sposób na osiągnięcie tego”. Musisz być w tym bardziej łagodny i robić więcej, jeśli chodzi o sprzedaż. Mógłbym powiedzieć, że zrobiłbym to zamiast tego, ponieważ prawdopodobnie poprawi to wydajność (generalnie sprawdzam kod SQL, w którym wydajność jest bardzo ważna). Mogę dodać kilka szczegółów na temat tego, dlaczego jest to lepszy wybór, tak jak zrobiłbym to, odpowiadając na pytanie dotyczące przepełnienia stosu. Mógłbym zauważyć, że zmiana tego kodu nie jest wymagana, ale należy wziąć pod uwagę zmianę w przyszłym kodowaniu. Zasadniczo z tego rodzaju komentarzami uczę osoby o mniejszym doświadczeniu w zakresie tego, co może działać lepiej.

Potem są komentarze „to działa, ale robimy to w ten sposób”. Prawdopodobnie będą to również wymagane zmiany. Obejmują one komentarze na temat standardów firmy lub architektury, której oczekujemy od nich. Odwołałbym się do dokumentu standardowego lub architektury i powiedziałbym im, żeby poprawili się do tego standardu. Komentarz byłby prosty, ale neutralny, brakuje go w ten sposób lub nazwy zmiennych nie są zgodne z naszym standardem nazewnictwa lub podobnymi rzeczami. Na przykład, nasza architektura pakietów SSIS wymaga, aby pakiet używał naszej bazy danych metadanych do przechowywania określonych informacji o pakiecie i wymaga szczególnego logowania. Pakiet działałby bez tych rzeczy, ale są one wymagane ze względów firmy (musimy na przykład zgłosić wskaźnik powodzenia importu lub przeanalizować rodzaje błędów, które otrzymujemy).

Jedyną rzeczą, której nie chcesz robić w komentarzach do recenzji kodu, jest atakowanie kogoś osobiście. Może to również pomóc, jeśli znajdziesz coś, co zrobili dobrze i zauważysz, że to było dobre. Czasami uczę się czegoś nowego na podstawie recenzji kodu, a jeśli tak, to mówię o tym osobie.

Jeśli kod jest zgodny ze standardami kodowania, ale zrobiłbyś to inaczej, musisz zadać sobie pytanie, czy to, co zrobili, jest złe.

Jeśli tak nie jest ... to po prostu nie tak, jak byś to zrobił i po prostu nie możesz tego zostawić, spróbuj po prostu zapytać: „Dlaczego zrobiłeś to w ten sposób, a nie w ten sposób?”. Następnie przekonujesz ich, aby zakwalifikowali się, dlaczego zrobili to tak, jak zrobili, nie mówiąc: „Zrobiłbym to w ten sposób, a ty też powinieneś…”

Możesz także nauczyć się czegoś w tym procesie.

Chcę przekazać swój punkt widzenia, nie będąc szorstkim.

Nie myl zwięzłości z byciem ściernym. Gdy coś stanowi problem, udokumentuj go w sposób zrozumiały dla każdego, kto go naprawi. Trzymaj się faktów i nie pisz eseju. To znaczy:

• Spowoduje to awarię frobnitz, gdy fooble znajdzie się w granicach 5 grimpingów współczynnika snorgatz.

• Ustaloną konwencją do tego jest wywoływanie fazzatz () za pomocą świeżo zainicjowanego Squidge. Zrób z tego metodę, aby zawsze odbywała się w ten sam sposób i nie była duplikowana.

  Nie chcę też sprawiać wrażenia, że ​​staram się być autorytatywny i mówić coś w stylu „To powinno być zrobione w ten sposób ...”, ale wciąż muszę zrozumieć, że to, co robią, nie jest zbyt dobre .

Celem przeglądu kodu jest umieszczenie na nim drugiej, zwykle bardziej doświadczonej, pary oczu, aby wykryć problemy. Jeśli jesteś w stanie osądzać pracę innych i istnieje uzasadniony powód, aby powiedzieć, że coś nie jest dobre, zlekceważysz swoją odpowiedzialność jako recenzenta, jeśli tego nie zrobisz.

Będą spory, a recenzent i recenzent mają okazję do obrony swoich pozycji. Jeśli jesteś rówieśnikiem i dojdziesz do impasu, znajdź kogoś starszego, by zerwać więź.

Zależy to od rodzaju zauważonego problemu

• brak powiadomienia copywrite - powszechny i ​​nudny problem - krótki komentarz z informacją o tym problemie i kontynuacja
• miejsca, w których mógłbym to zrobić inaczej - zwykle zadają tutaj pytania, a nie wypowiadają się, czasami odpowiedzi uzasadniają oryginalne rozwiązanie innym razem nie, a następnie mogę zająć się nimi bardziej precyzyjnie
• miejsca, w których występuje wyraźna wada, np. nadpisanie równe, które może przepełnić stos - sięgnij po czerwony długopis - oznacz go jako wadę i wyraźnie określ, dlaczego jest uszkodzony - sprawdź także inne podobne obszary, aby sprawdzić, czy nie wystąpił systematyczny problem.

Z mojego doświadczenia:

1. Zawsze miej przy sobie autora kodu podczas przeglądania jego kodu. Najlepiej, jeśli kod jest wyświetlany na tablicy i oboje możecie go bardzo dobrze zobaczyć.

2. Miej przyjazną rozmowę. Doceń dobrą część kodowania. Powiedz mu, że „to jest najlepsze, co widziałem”, jeśli widzisz kilka dobrych części w kodzie.

3. Poproś go o sprawdzenie Twojego kodu oraz zaakceptowanie i zaakceptowanie poprawnych punktów i poprawienie go. Uszanuj jego komentarze w twoim kodzie, a on automatycznie uszanuje twoje komentarze do recenzji kodu.
4. Radzić sobie z tym na poziomie programisty, chyba że jest to bardzo ważne lub potrzeba więcej czasu, aby rozwiązać problemy z przeglądaniem kodu. Nie eskaluj do menedżerów z powodu prostych problemów, jeśli brakuje warunków.
5. Spójrz z perspektywy „Uczenie się z innego kodu” zamiast wskazywania błędów w kodzie.
6. Podczas sesji przeglądu kodu przytaczaj błędy, które popełniłeś w przeszłości, oraz to, w jaki sposób recenzje kodów pomogły ci i uniknęły dużych problemów produkcyjnych, ponieważ pomógł ci inny zestaw oczu.
7. Być pokornym. Więcej uznania i mniej komentarzy do niego :) Dowiesz się dużo podczas przeglądu kodu, a on chętnie zaakceptuje twoje komentarze.