Jak oznaczać zmiany w projekcie żeby był z tego pożytek dla nas i dla innych?

Commit niejedno ma imię

Podczas wysyłania zmiany w git zostajesz poproszony o podanie komunikatu dotyczącego danej zmiany. Miliony programistów robią to – powiedzmy - kilkanaście razy dziennie. W rezultacie commity mają bardzo różne opisy – zarówno jeśli chodzi o style jak i jakość. Powiedzmy sobie szczerze - zbyt często podczas sprawdzania nowego projektu stwierdzamy, że historia commitów to długi ciąg jednowierszowych komunikatów, oferujących jedynie pobieżne informacje o tym, co się zmieniło.

Szkoły są generalnie dwie: jedni piszą zwięzłe one linery a inni wręcz elaboraty szczegółowo listujące poszczególne zmiany i nie pomijające żadnych, nawet najmniej istotnych, technicznych szczegółów.

Co to jest „dobry commit”?

Dobry komunikat dotyczący zmiany to komunikat, który zapewnia odpowiedni kontekst i uzasadnienie wprowadzanej zmiany.

W przypadku poprawiania literówki może to być Fixed typo, ponieważ zmiana jest naprawdę oczywista. W przypadku naprawienia trudnego do wyśledzenia błędu może to już oznaczać pół strony tekstu z akapitami, linkami i odnośnikami do informacji, które pomagają w zrozumieniu wprowadzanej zmiany.

Długość dobrego komunikatu o zmianach niekoniecznie jest związana z rozmiarem pliku diff. Niektóre zmiany zajmujące tylko jeden wiersz kodu wymagają wyjaśnienia rozpisanego w commit na wiele akapitów. A z kolei inny commit, który dotyczy stu plików, może być całkiem przyziemny i wymagać tylko jednego lub dwóch zdań w opisie commita.

Ważne jest to, aby na wszystkie pytania dotyczące danej zmiany można było znaleźć odpowiedzi w opisie commita.

Ale po co w ogóle się starać…

Najlepszym powodem solidnego przygotowania wiadomości jest pomoc ludziom w zrozumieniu wprowadzanych zmian. Chodzi np. o takie sytuacje:

• Twój kolega robi przegląd kodu tego samego dnia, w którym go wykonałeś.
• Członek zespołu próbuje zrozumieć Twoją zmianę tydzień później, kiedy jesteś na wakacjach.
• Nowy programista dołączający do projektu chce poznać powód, dla którego kod jest w takim stanie, w jakim się znajduje.
• Próbujesz zrozumieć własne zmiany sześć miesięcy później.

Sprawdź oferty pracy na TeamQuest

Po opisie commita chcemy wiedzieć, dlaczego dokonano zmiany i jakie założenia lub wiedzę posiadał wprowadzający, dokonując zmiany. Pomaga to przyszłym programistom zrozumieć przyczyny tych zmian.

Jak to robić?

Napisanie jasnego i wyczerpującego komunikatu o zatwierdzeniu może stanowić okazję do refleksji nad samymi zmianami – działa trochę jak taki mini przegląd kodu. Przejrzyj więc diffa podczas pisania opisu commita. Możesz upewnić się, że rozumiesz co napisałeś i jesteś zadowolony ze zmian, które widzisz, oraz że Twoja wiadomość o zatwierdzeniu obejmuje wszystko, co może nie być jasne dla innych (albo dla Ciebie samego za jakiś czas). Przy okazji odkryjesz może jeszcze jakieś pozostawione printy w rodzaju System.out.println(„test”); ;-)

Warto zawrzeć odniesienia do źródeł informacji, np. oficjalnej dokumentacji lub pytań i odpowiedzi na StackOverflow, które pomogły Ci dojść do zestawu wprowadzonych zmian. Powinieneś wyjaśnić wszelkie wprowadzone zmiany a możesz również wyjaśnić rzeczy, które Twoim zdaniem mogłyby być lepsze, ale z różnych powodów nie miałeś czasu na ich dodanie lub też zrobiłeś to na razie może nie w najbardziej optymalny sposób ale pozwalający na szybkie usunięcie buga.