Git - jak komentować we własnym projekcie [PYTANIE POCZĄTKUJĄCEGO]

Hej
Zaczynam własny projekcik klepać mały taki trochę

Chciałbym jakoś sensownie sobie zmiany opisywać w gicie, żeby poćwiczyć i angielski, w przyszłości chcę być konserem git'a

Czy takie zasady pisania commit message są ok?

-> Krótki tytuł w trybie rozkazującym
-> Linijka przerwy
-> Dokładniejszy opis (2 - 3 zdania odpowiadające na to, co i jak, ale już w czasie przeszłym)
-> Wszystko po angielsku
-> Jak jakiś mały commit z samoopisującym się tytułem, do dokładniejszy opis olewam

Podobne zasady znalazłem na takim screenie, ale te limity znaków bym olał.

Jak najbardziej OK.

Dużo zależy od projektu. Dobra zmiana w dobrze utrzymanym projekcie może nie wymagać niczego więcej niż linijka tytułowa, bo zmiana ma 4 zmienione linijki, które mówią same za siebie. Tytuł commita wtedy jest tylko po to, żeby łatwo było znaleźć zmianę w logu. Dalsze komentarze są potrzebne jeśli są jakieś mało oczywiste szczegóły. Myślę, że tutaj jest tak samo jak z komentarzami w kodzie – najlepiej, żeby ich nie było. Jeśli możesz rozwiązać problem niezrozumiałości kodu wydzielając funkcję, pisząc test dokumentujący czy zapisując kod inaczej, lepiej tak zrobić. Oczwiście nie zawsze jest to możliwe, zwłaszcza w dużym projekcie ze zmiennym stabnem, dużą dawką spaghetti, gdzie często jesteśmy zmuszeni do stosowania obejść.

Jak sobie wysoko postawisz poprzeczkę to szybciej ci się odechce i zaczniesz pisać: small fixes albo: refactoring niż kiedy ta poprzeczka będzie znacznie niżej na początku.
Zacząłbym od ścisłego przestrzegania formy literackiej: zaczynamy z dużej (czy jak tam kto woli ogromnej) litery, kończymy kropką.

przyszły_konerser_gita napisał(a):

-> Dokładniejszy opis (2 - 3 zdania odpowiadające na to, co i jak, ale już w czasie przeszłym)

Kto to będzie czytał? Albo twój feature/fix bedzie działał albo nie. Jak będzie to nie ma po co, a jak nie będzie to chyba na głowę ktoś by musiał upaść, żeby czytać te baśnie zamiast sprawdzić np. diffem, czy narzędziami w IDE albo webowymi na repo co tam schrzaniłeś. Nie rób jakichś gównianych oszczędności i udziwnień tylko pisz kod tak, żeby było wiadomo co robi - przyda się i Tobie i innym. Np. nie ma nic gorszego, niż dodanie błednego opisu, bo mózg sie wstępnie fiksuje na opisie, zamiast na tym co faktycznie jest nawywijane w kodzie. To moja prywatna opinia i nie biorę odpowiedzialności za ewentualne straty :D

Dobry opis nie jest zly.

Czasem zmiana ma takie bugi (ficzery) ze zachodzisz w glowe o co chodzilo autorowi, w jakim swiecie zyl ten czlowiek i jaki mial stan emocjonalny ze popelnil ten czy inny kod.

Opis, dla mnie najlepszy w formie historii pozwala przekazac chociaz czesc pobudek autora.

Chciałbym jakoś sensownie sobie zmiany opisywać w gicie, żeby poćwiczyć i angielski, w przyszłości chcę być konserem git'a

No to przede wszystkim odwróć to co robisz. Zacznij je na początku pisać, przed zmianą czegokolwiek w projekcie, zacznij od tytułu, a zmiany jakie wprowadzisz podporządkuj temu tytułowi.

Jeśli Twoje komentarze są pochodną Twojej pracy to już z miejsca Ci mówię, że masz je słabe :D Możesz spełniać wszystkie punkty jakie wypisujesz, ale to tylko wygładzanie tego co i tak nie przesądza o istocie commitu.

W 99.999999999% sytuacji ludzie piszą commit po fakcie. Co to zmienia? W dużym stopniu częściej wtedy podpisują niejednoznaczą zmianę. Jak będziesz sprawniejszy w git możesz wydzielać te zmiany, ale 1) łatwiej wtedy o błąd w commicie, 2) i tak jesteś pod ścianą, bo nie wszystko z kodu wydzielisz, a przynajmniej nie jest to czasowo optymalne podejście.

Także możesz wtedy spełniać wszystkie kryteria o jakich piszesz, byc poprawnym do bólu, ale gdy przyjdzie podpisywać zmianę to i tak będziesz zaciemniać.

Nie chce podcinać skrzydeł, ale inwestowanie nie wiadomo ile czasu w naukę i pisanie komentarzy w Gicie nie ma sensu.

1. Jeśli chcesz poćwiczyć angielski to jest 666 lepszych sposobów
2. W praktyce w komentarzu umieszcza się jakiś odnośnik np. numer Jiry w ramach której robiona była zmiana + jakiś tam dopisek, którego i tak nikt nie czyta
3. Jeśli na projekcie kultura pisania komentarzy będzie w stylu „WiP”, to chociażbyś pisał eseje - wartość będzie znikoma. Nie wyobrażam sobie tez przesadnego ewangelizowanie w tym zakresie, ponieważ wszystko rozbija się o pragmatyzm i celowość tych komentarzy.
4. Komentarze kłamią, czy to w kodzie czy w Gicie.

W Git stosuje zazwyczaj nr taska plus 4-6 słów komentarza. Jak chcesz się czegoś nauczyć to radzę zacząć od spisania zadań w taskach i potem ich realizację. W projektach 1 osobowych to zazwyczaj przerost formy nad treścią ale jak kolega wyżej wspomniał najpierw pracę planuj a potem realizuj. Opisywanie historii ma mały sens.