Jak dobrze opisać commit git?

Profesjonalny programista od amatora różni się tym, co ekspert od profesjonalisty. Wszystkim o jeden poziom.

Kiedyś napisałem o tym, jak na różne sposoby można dokumentować kod. Część dokumentacji może być utworzona poprzez testy automatyczne, część przez README lub za pomocą komentarzy w kodzie. Chciałbym jednak zwrócić uwagę na jeszcze jeden bardzo istotny sposób dokumentowania kodu. Z wykorzystaniem commitów Git. W tym artykule opowiem o tym, jak dobrze opisać commit by był częścią dokumentacji projektowej.

Wady dokumentacji

Głównym problemem w dokumentowaniu kodu jest to, że okropnie szybko staje się ona przestarzała – szczególnie przy dynamicznie rozwijających się aplikacjach. Oznacza to, że oprócz zarządzania samym kodem, należy zarządzać też dokumentacją, a to generuje dodatkowe koszty.

Dokumentacja sama w sobie jest czymś pożądanym, niemniej ze względu na dodatkowy czas który trzeba na nią alokować, dbać by była aktualna, wszystko to sprawia, że często ciężko jest znaleźć chwilę na dokumentowanie projektu.

Jak dokumentować dobrze?

Mam zasadę, by wszystko, co jest opisane publicznie miało swój test automatyczny. Jeżeli cokolwiek zmieniam w dokumentacji, dodaję pokrywający tę zmianę test. Dzięki temu nawet jeśli fragmenty dokumentacji będą trochę przestarzałe, mam pewność że opisane w nich rzeczy nadal będą działać.

Co jednak w przypadku gdy projekt jest na tyle duży, że powód dodania lub zmiany poszczególnych elementów kodu staje się trudny do zrozumienia?

W takich wypadkach można dodawać komentarze do kodu, ale ja jako programista dodający kod wiem co i po co zmieniam. Ciężko jest przewidzieć która linijka będzie niezrozumiała w przyszłości dla kogoś innego kto na nią spojrzy.

Ponadto przestarzałe komentarze nie wywalają testów. I z doświadczenia wiem, że najszybciej stają się nieadekwatne do tego co opisują.

Pewnym krokiem do przodu są takie rozwiązania jak PHPdoc, czyli standardy komentowania umożliwiające wygenerowanie dokumentacji na podstawie komentarzy w kodzie. Nie rozwiązuje to problemu zarządzania dodatkowym kodem, ale nie wydaje mi się, by dało się tego uniknąć gdy chcemy posiadać dokumentację projektu. W ruby osobiście preferuję rozwiązania takie narzędzia jak rspec-api-documentation, które pozwalają generować dokumentację na podstawie testów, a nie komentarzy, gdyż błędy w testach łatwiej wykryć gdy przestaną przechodzić.

Dokumentowanie na bierząco jest jednak trudne, dlatego najlepszą dokumentacją kodu w pewnym zakresie staje się dobry opis commita. Programista zawsze może użyć

git blame nazwa_pliku | grep 'nr_lini)'

by zobaczyć, w którym commicie została ostatnio zmieniona linijka i podejrzeć jego opis.

Gdy commit zostanie dobrze opisany, przyśpieszy to sprawdzenie zmiany przez innych deweloperów, ale także doda informację o zmianach przy wypuszczaniu uaktualnionej wersji oraz będzie widoczny w historii projektu dla każdego, kto zechce w przyszłości pracować nad tym samym kodem (to możesz być też ty).

Dobrze opisany commit sprawia że:

opis zmiany jest zawsze aktualny
zmiana jest wyjaśniona w kontekście, z linkami referencyjnymi, kartą do managera zadań itp.
oprócz opisu zmian mamy także informacje o dacie zmiany, autorze i osobach sprawdzających kod.

Oto dlaczego dobrze opisane commity są tak istotne.

Zaraz zaraz, ale to dodatkowa praca….

Dobrze opisane commity to twoja wizytówka jako programisty, ale każdy chce być produktywny i unikać straty czasu na przygotowywanie obszernych opisów zmian. To nie byłby blog o produktywności, gdybym tego od Ciebie wymagał!

Jak dobrze opisać commit?

Opis zmiany powinien zawierać trzy istotne informacje:

Krótkie podsumowanie zmian (będące tytułem commita)
Szczegółowy opis zmiany, dlaczego została wprowadzona i co obejmuje.
Referencje, jeśli zmiana zależy od innych elementów repozytorium.

Przyjrzyjmy się teraz poszczególnym elementom opisu

Tytuł commita

Pierwsza linijka commita czasem jest traktowana jako temat wiadomości email, podczas gdy pozostałe informacje zawarte w opisie to jej tekst. Pusta linia między tytułem a pierwszym paragrafem pozwala na poprawne oddzielenie tytułu od reszty informacji o zmianach.

Tytuł nie powinien mieć więcej niż 50 znaków. Dłuższe tytuły zostaną ucięte na Githubie i Bitbucketcie przez co nie będą zbyt czytelne. Poniżej dwa zdjęcia pokazujące różnicę między dobrym i złym tytułem Git.

Tytuł commita do 50 znaków, po odzieleniu pustą linią od reszty wiadomości prezentuje się bardzo dobrze na githubie

Zbyt dugi tytuł commita powoduje ucięcie tekstu

Zbyt długi tytuł powoduje ucięcie tekstu w tytule, przez co zmiana jest nieczytelna.

Jak przygotować dobry opis commita

Oddzielając tytuł commita od szczegółowego opisu możemy przygotować dowolnie dokładne wyjaśnienie zmian w kodzie. Dobrze przygotowany opis powinien zawierać: