TeamQuest Blog

Dobre opisy commitów

Dobre opisy commitów

Marcin Sarna , 12.04.2021 r.

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.

Mid/ Senior Java Developer 15000 - 17000 PLN

Warszawa
Aplikuj

Node.js Regular Developer

Kraków
Aplikuj

PHP Developer 4000 - 7000 PLN

Częstochowa
Aplikuj

Analityk Systemowy-Biznesowy

Praca zdalna
Aplikuj

Regular T-SQL Developer

Kraków
Aplikuj

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.

Najnowsze oferty pracy:

Polecane wpisy na blogu IT:

Szukasz pracownika IT?

Dostarczymy Ci najlepszych specjalistów z branży IT. Wyślij zapytanie

Wyrażam zgodę TeamQuest Sp. z o.o. na przetwarzanie moich danych osobowych w celu marketingu produktów i usług własnych TeamQuest, w tym na kontaktowanie się ze mną w formie połączenia telefonicznego lub środkami elektronicznymi.
Administratorem podanych przez Ciebie danych osobowych jest TeamQuest Sp. z o.o., z siedzibą w Warszawie (00-814), ul. Miedziana 3a/21, zwana dalej „Administratorem".
Jeśli masz jakiekolwiek pytania odnośnie przetwarzania przez nas Twoich danych, skontaktuj się z naszym Inspektorem Ochrony Danych (IOD). Do Twojej dyspozycji jest pod adresem e-mail: office@teamquest.pl.
W jakim celu i na jakiej podstawie będziemy wykorzystywać Twoje dane? Dowiedz się więcej