Czy warto używać „dziennika zmian” w każdym pliku kodu, gdy używasz kontroli wersji?

75

Miałem wrażenie, że system kontroli wersji wyeliminował potrzebę umieszczania „dzienników zmian” wszędzie w kodzie. Często widziałem ciągłe korzystanie z dzienników zmian, w tym dużych długich bloków na początku procedur przechowywanych z dużą sekcją zablokowaną dla zmian w pliku i zaśmiecającą kod takimi rzeczami jak:

// 2011-06-14 (John Smith) Change XYZ to ABC to fix Bug #999

i:

// 2009-95-12 (Bob Jones) Extracted this code to Class Foo 
// <commented-out code here>

Powodem tego, jak mi wyjaśniono, jest to, że przesiewanie naszych dzienników VCS trwa zbyt długo, aby dowiedzieć się, kto co i dlaczego zmienił, mając go w samym pliku kodu, na górze lub w pobliżu odpowiedniego zmiana, ułatwia sprawdzenie, kto i co zmienił. Chociaż widzę w tym sens, wydaje się to zbędne i po prostu trochę klepnięć: „Eee, tak naprawdę nie rozumiemy, jak właściwie korzystać z naszego VCS, więc w ogóle nie będziemy się tym przejmować”.

Co myślisz? Czy używasz zarówno komentarzy, jak i dziennika? Tylko dziennik? Czy uważasz, że łatwiej jest kodować, gdy widać nad blokiem kodu, że John Smith zmienił metodę sprawdzania XYZ tydzień temu, zamiast konieczności przeszukiwania dzienników i porównywania plików kodu w narzędziu Diff?

EDYCJA: Używając SVN, ale zasadniczo tylko jako repozytorium. Bez oddziałów, bez scalania, nic oprócz logów + pamięci.

Wayne Molina
źródło
4
Z jakiego systemu kontroli wersji korzystasz?
ChrisF
11
Niektóre sklepy korzystały z dzienników zmian, zanim istniały systemy kontroli źródła. Bezwładność i znajomość utrzymują dzienniki zmian w pobliżu.
Gilbert Le Blanc
2
+1 - Mój zespół też to robi i starałem się przekonać niektórych z nich, że jest to rola VCS. Problemy zaczynają się, gdy te komentarze nie są na bieżąco z rzeczywistym kodem ... A najgorsze jest to, że kierownictwo postanowiło dodać dzienniki zmian do każdej metody.
slaphappy
2
+1 - Walczę o to z naszym starszym deweloperem od prawie dwóch lat. Jego jedynym uzasadnieniem dla dodania tych bezużytecznych komentarzy jest to, że ułatwia to scalanie zmian w metodach 3000-liniowych. Pomysł, że metoda 3000 linii jest obsceniczna, spotkał się z pogardą.
Joshua Smith,
1
Jeśli „przeszukanie [twoich] dzienników VCS trwa zbyt długo”, robisz coś złego.
Keith Thompson

Odpowiedzi:

45

Zwykle usuwam komentarze w kodzie. I przez usunięcie, mam na myśli, z uprzedzeniem . O ile komentarz nie wyjaśnia, dlaczego dana funkcja coś robi, znika. PA pa. Nie przechodź.

Nie powinno cię zatem dziwić, że usunę te dzienniki zmian z tego samego powodu.

Problem z komentowanym kodem i komentarzami, które czytają jak książki, polega na tym, że tak naprawdę nie wiesz, jak jest on odpowiedni i daje fałszywe poczucie zrozumienia, co tak naprawdę robi kod.

Wygląda na to, że Twój zespół nie ma dobrego oprzyrządowania wokół systemu kontroli wersji. Ponieważ powiedziałeś, że używasz Subversion, chciałbym zauważyć, że istnieje wiele narzędzi, które pomogą Ci zarządzać repozytorium Subversion. Od możliwości poruszania się po źródle przez Internet, do łączenia zestawów zmian z konkretnymi błędami, możesz zrobić wiele, co zmniejsza potrzebę tworzenia tych „dzienników zmian”.

Miałem mnóstwo ludzi, którzy komentowali i mówili, że być może mylę się co do usuwania komentarzy. Ogromna większość kodu, który widziałem, który został skomentowany, to zły kod, a komentarze tylko zaciemniły problem. W rzeczywistości, jeśli kiedykolwiek skomentuję kod, możesz być pewny, że proszę o wybaczenie od programisty konserwacji, ponieważ jestem stosunkowo pewien, że będą chcieli mnie zabić.

Ale jeśli nie uważasz, że powiem, że komentarze powinny być usunięte w żartach, to przesłanie Daily WTF (z bazy kodu, nad którą pracowałem) doskonale ilustruje mój punkt widzenia:

/// The GaidenCommand is a specialized Command for use by the
/// CommandManager.
///
/// Note, the word "gaiden" is Japanese and means "side story",
/// see "http://en.wikipedia.org/wiki/Gaiden".
/// Why did I call this "GaidenCommand"? Because it's very similar to
/// a regular Command, but it serves the CommandManager in a different
/// way, and it is not the same as a regular "Command". Also
/// "CommandManagerCommand" is far too long to write. I also toyed with
/// calling this the "AlephCommand", Aleph being a silent Hebrew
/// letter, but Gaiden sounded better.

Och ... Historie, które mógłbym Wam opowiedzieć o bazie kodu, i zrobię to, tyle że wciąż jest używana przez jedną z największych organizacji rządowych w okolicy.

George Stocker
źródło
4
Ilekroć mam problem ze złożoną logiką, komentarze mogą czasem pomóc mi zrozumieć kontekst, dlaczego logika jest tak skomplikowana, jak jest. Ale ogólnie zgadzam się z tobą.
wałek klonowy
5
Każdy programista ma co najmniej kilka złych cech, wiem, że nie powinienem, ale nie mogę przestać :) Za każdym razem, gdy piszę TODOkomentarz, umiera szczeniak.
wałek klonowy
32
Usuwanie komentarzy innych osób z uprzedzeniami w pewien sposób wymusza własny styl programowania i wiarę w innych. Młodsi i pacyfistyczni programiści nie będą szczekać, ale od czasu do czasu napotykasz mężczyznę alfa, a potem zaczyna się walka, która nie powinna była się rozpocząć. Czytałeś więc na inteligentnym blogu inteligentnego człowieka, że ​​jeśli chodzi o komentarze, mniej znaczy więcej. Inni mogli nie przeczytać tej samej książki. Nawet jeśli uważasz, że masz rację, ponieważ kilka osób na SO z 5k + rep zgadza się, dyktatura nie jest sposobem na podjęcie współpracy. Pracowałem wcześniej pod samcem alfa i zrezygnowałem.
Job
8
@Neil Butterworth: re: ructions: Kod ma być ciągliwy. Przebuduj go, zmień, popraw. To jest przeznaczone do tego. To nie powinno być napisane tylko raz. Nasze rozumienie zmian biznesowych i kiedy to nastąpi, musimy zmienić kod. Mam wiele problemów z komentarzami, ale najbardziej istotne w naszej dyskusji jest to, że komentarze rzadko synchronizują się z kodem i ogólnie nie wyjaśniają, dlaczego coś się dzieje. Kiedy tak się dzieje, łatwo go usunąć. Jeśli ktoś przyjdzie do mnie i zapyta, dlaczego usunąłem następujący komentarz file.Open() // Open the file. Śmiałbym się.
George Stocker
5
Kilka dni temu napisałem kawałek kodu, bardzo złożone obliczenia matematyczne pełne trygonometrii, transformacji, cokolwiek ... Zajęło mi około półtorej godziny napisanie mniej niż 10 linii kodu. Prawie nikt wokół mnie nie rozumie, jak to działa. Nie zrozumiem tego również za kilka tygodni. Z drugiej strony, dlaczego jest to banalne. Tak więc powyżej tych kilku wierszy znajduje się cały rozdział tekstu, wyjaśniający co, a nie dlaczego. Jeśli przyszedłeś i skasowałeś ten komentarz, uderzyłbym cię w twarz, pieprzyłbym się.
Davor Ždralo
76

Te „dzienniki zmian” osadzone w kodzie są szczególnie naff. Po prostu pokazują się jako kolejna różnica, gdy różnisz się wersjami, i taka, na której tak naprawdę nie zależy. Zaufaj swojemu VCS - większość z nich ma funkcję „obwiniania”, która bardzo szybko pokaże, kto co zmienił.

Oczywiście naprawdę okropną rzeczą była funkcja „starych” VCS, w której można było osadzić rzeczywisty dziennik VCS w plikach źródłowych. Uniemożliwiło scalenie prawie niemożliwe.

Neil Butterworth
źródło
14
Pojawiają się one nie tylko jako kolejna różnica, co gorsza, ale z czasem mogą się również mylić , podczas gdy każdy dobry VCS zawsze będzie w stanie powiedzieć, kto naprawdę napisał konkretną linię, a także historię wokół tej linii. Jedyne, co gorsze niż bezużyteczne komentarze, to szkodliwe komentarze. Te komentarze zaczynają się jako bezużyteczne i ostatecznie stają się szkodliwe, jeśli nie całkowicie ignorowane.
Ben Hocking
10

Mam jeden plik ChangeLog dla każdego projektu, który jest automatycznie zapełniany przez niektóre komunikaty zatwierdzania.

Nie mamy osadzonych komentarzy ChangeLog. Gdybyśmy to zrobili, usunęłbym je i porozmawiałem z osobą, która je doda. Myślę, że wskazują na niezrozumienie narzędzi, których używasz, w szczególności vcs.

Mamy format komunikatów zatwierdzania, który ułatwia przeglądanie dzienników. Nie zezwalamy również na bezużyteczne lub niejednoznaczne komunikaty zatwierdzania.

dietbuddha
źródło
8

Osobiście nie znoszę zmieniać dzienników w pliku źródłowym kodu. Wydaje mi się, że narusza to zasadę inżynierii oprogramowania, ponieważ wszelkie zmiany, które wprowadzam, muszą być wprowadzane w wielu miejscach. Wiele razy informacje dziennika zmian są całkowicie bezużyteczne i nieważne. Moim skromnym zdaniem zmiany w oprogramowaniu powinny być udokumentowane po wpisaniu kodu.

Ale co ja wiem ...

Myślę, że jeśli istnieje potrzeba wdrożenia praktyki przechowywania dziennika zmian w kodzie źródłowym, dziennik zmian powinien być ograniczony do zmian, które wpływają na interfejs API / interfejs puli klasy. Jeśli wprowadzasz zmiany w klasie, które nie będą łamały żadnego kodu, który jej używa, zapisanie tych zmian w dzienniku zmian jest po prostu bałaganem. Widzę jednak, jak czasem może być przydatne sprawdzenie górnej części pliku kodu źródłowego pod kątem dokumentacji wszelkich zmian, które mogły uszkodzić cokolwiek innego. Tylko podsumowanie, w jaki sposób zmiana może wpłynąć na interfejs API i dlaczego została wprowadzona.

Z drugiej strony, mój sklep zajmuje się głównie C # i zawsze używamy wbudowanych komentarzy XML do udokumentowania naszego API, więc czytanie dokumentacji na temat publicznych zmian API jest mniej więcej tak proste, jak wykorzystanie inteligencji.

Myślę, że naleganie na dziennik zmian w pliku źródłowym po prostu dodaje niepotrzebne tarcie do maszyny i niweczy jeden z celów wdrożenia systemu kontroli wersji.

John Connelly
źródło
6

Ostatnia firma, w której pracowałem, miała oprogramowanie, które miało 17 lat historii, rozwoju i corocznych aktualizacji. Nie wszystkie migracje z jednego systemu kontroli wersji do drugiego zachowałyby komentarze lub uwagi do odprawy. W ciągu tych lat nie wszyscy programiści zachowali też spójność z komentarzami / uwagami dotyczącymi odprawy.

Z komentarzami w kodzie źródłowym, archeologiczna historia zmian była przechowywana jako notatki, a nie komentarze w kodzie. I tak, nadal wysyłają kod VB6.

Tangurena
źródło
5

Kontrola wersji może zastąpić komentarze do dziennika zmian w kodzie, jeśli deweloperzy z twojego zespołu prawidłowo go używają.

Jeśli Twój zespół nie dodaje komentarzy przy odprawie lub pozostawia nieprzydatne komentarze, trudno będzie znaleźć informacje, których szukasz w przyszłości.

W mojej obecnej firmie jesteśmy zobowiązani do zgłaszania uwag przy każdym zameldowaniu. Nie tylko to, ale oczekuje się, że do każdego odprawy dołączymy bilet w Jira. Kiedy spojrzysz w Jira w przyszłości, zobaczysz każdy plik, który został zarejestrowany i kiedy w związku z tym problemem, wraz z pozostawionym komentarzem. To całkiem przydatne.

Zasadniczo kontrola wersji to tylko narzędzie, to sposób, w jaki zespół używa tego narzędzia, które zapewni korzyści, których szukasz. Wszyscy członkowie zespołu muszą zgodzić się z tym, w jaki sposób będą go używać, aby jak najlepiej zapewnić śledzenie błędów, a także czyste wersje kodu.

Tyanna
źródło
5

Jest to pozostałość po czasach, gdy dzienniki VCS były mylące, a systemy VCS były trudne w obsłudze (pamiętam te czasy, gdzieś na zapleczu lat 80-tych).

Twoje podejrzenia są całkowicie poprawne, te komentarze są bardziej przeszkodą niż pomocą, a każdy nowoczesny VCS pozwoli ci znaleźć dokładnie to, czego szukasz. Oczywiście ty (i twoi koledzy) będziesz musiał wydać ok. 30–60 minut na naukę obsługi wszystkich tych funkcji (co, jak podejrzewam, jest faktycznie powodem, dla którego te komentarze nadal istnieją).

Trzymam to (prawie) u George'a. Komentarze w kodzie są naprawdę uzasadnione tylko wtedy, gdy wyjaśniają coś, co nie jest natychmiast widoczne w samym kodzie. I to zdarza się rzadko w dobrym kodzie. Jeśli potrzebujesz mieć dużo komentarzy w swoim kodzie, to jest to jego własny zapach i krzyczy „refaktoryzuj mnie!”.

wolfgangsz
źródło
4

Nadal uwzględniamy je w źródle procedur składowanych, ponieważ w ten sposób możemy dokładnie określić, która wersja jest zainstalowana na kliencie. Reszta aplikacji jest kompilowana rozproszona, więc mamy numery wersji modułów, które prowadzą z powrotem do źródła, ale SP są dystrybuowane jako źródło do klientów w celu lokalnej kompilacji w bazie danych.

Nasz dotychczasowy kod PowerBuilder nadal ich używa, ale myślę, że jest to tylko czynnik zapewniający komfort dla niektórych podglądaczy. To również jest kompilowane do dystrybucji, więc (IMO powinni) korzystać z cholernej historii VCS.

DaveE
źródło
1
+1 Zamierzałem napisać tę odpowiedź, ale oszczędziłeś mi kłopotów. Nie tylko procedury składowane są dystrybuowane jako źródło, ale także wiele języków skryptowych. Często używam OpenACS i TCL - często, jeśli klient ma rozwidloną wersję określonego pliku, jedynym GWARANCJĄ jest, abyś wiedział, którą wersję ma, czytając dziennik zmian. Szczególnie przydatny, jeśli jesteś zalogowany na stronie klienta i nie możesz łatwo zrobić różnic w oprogramowaniu do kontroli wersji.
TrojanName
3

Jeśli używasz SVN, zrobienie tego jest stratą czasu i całkowicie bezużyteczne.

SVN ma funkcję obwiniania. Dzięki temu dowiesz się dokładnie, kto i kiedy utworzył każdą linię w danym pliku.

Jaka jest nazwa?
źródło
1

Komentarze do dziennika zmian są wyjątkowo pomocne w kodzie, gdy pomagają późniejszemu programistowi zadawać lepsze pytania dotyczące nowych wymagań. Gdy deweloper widzi na przykład komentarz, że Fred wymagał pola Foo 6 miesięcy temu, aby spełnić pewne wymagania, programista wie, że musi zadać pytanie przed wdrożeniem ostatniego żądania, aby Foo było opcjonalne. Kiedy masz do czynienia ze złożonymi systemami, różni interesariusze mogą mieć różne priorytety i różne pragnienia. Komentarze do dziennika zmian mogą być bardzo pomocne w dokumentowaniu, które z tych kompromisów zostały dokonane, aby uniknąć problemów w przyszłości.

Teraz, jeśli każdy programista sprawdziłby pełną historię każdego wiersza kodu przed dokonaniem jakiejkolwiek zmiany, umieszczenie tych komentarzy w kodzie byłoby zbędne. Jest to jednak bardzo nierealne zarówno z punktu widzenia przepływu pracy - większość programistów zmieniłaby tylko sprawdzanie poprawności bez badania historii, kto ją dodał i dlaczego - oraz z technologicznego punktu widzenia - system kontroli wersji miałby trudności ze śledzeniem „tego samego "wiersz kodu, jeśli został przeniesiony z jednego wiersza do drugiego lub został przekształcony w inną klasę. Komentarze w kodzie są znacznie bardziej widoczne i, co ważniejsze, zachęcają kolejnych programistów do zauważenia, że ​​pozornie prosta zmiana może nie być taka prosta.

Biorąc to pod uwagę, komentarze do dziennika zmian w kodzie powinny być stosunkowo rzadkie. Nie opowiadam się za dodawaniem komentarzy do dziennika zmian za każdym razem, gdy odrobina kodu jest refaktoryzowana lub gdy naprawiony jest prawdziwy błąd. Ale jeśli pierwotnym wymaganiem było „Foo jest opcjonalne”, a ktoś przyjdzie i zmieni wymaganie na „Foo jest wymagane, aby wesprzeć dalszy pasek procesu”, jest to coś, co zdecydowanie rozważałbym dodanie komentarza. Ponieważ istnieje duża możliwość, że jakiś przyszły użytkownik / analityk nie będzie wiedział o dalszym procesie Bar i nie będzie wiedział, dlaczego Foo było wymagane, i poprosi o ponowne włączenie Foo i spowoduje ból głowy w procesie Bar.

I to przed rozważeniem, że organizacje mogą zdecydować się na zmianę systemu kontroli wersji z pewną częstotliwością, szczególnie, że rozwijają się od małych firm z garstką programistów do znacznie większych firm. Migracje te często powodują utratę komentarzy do dziennika zmian - tylko komentarze w kodzie zostaną zachowane.

Justin Cave
źródło
Czy są jakieś konwersje VCS, które nie zachowują komunikatów zatwierdzania?
David Thornley,
1
@David - widziałem wiele takich rzeczy. Nie wiem, czy były to przeszkody techniczne, czy też ktoś zdecydował, że łatwiej jest po prostu „zacząć od nowa” i sprawdzić cały kod do nowego VCS w dniu 1.
Justin Cave
dodanie komentarza wyjaśniającego, dlaczego zmienił się proces, może być przydatne, a czasem dodanie komentarza wyjaśniającego, kiedy się zmienił, ale nie widzę sensu umieszczania tego komentarza w formie dziennika zmian. Po pierwsze, nieco ukrywa użyteczność komentarza („Och, to tylko komentarz do dziennika zmian”), a po drugie, zachęca do dalszych, niepotrzebnych komentarzy do dziennika zmian (wzmocnienie nr 1).
Ben Hocking
Zrezygnować z bezpiecznego źródła wizualnego? Wszystkie przydatne nowoczesne systemy kontroli źródła poprawnie obsługują dzienniki zmian. Znamy to z definicji, ponieważ gdyby tego nie zrobili, nie byliby uznani za użytecznych. Poświęć 30 minut na naukę korzystania z kontroli źródła, którą masz, dzięki czemu będziesz o wiele bardziej skuteczny niż tylko modlenie się przez kogoś, kto wie, że twoje narzędzia oszczędzą ci trochę okruchów. Nie wspominając, że dość często historia kodu jest nieistotna, testujesz i piszesz teraz, teraz.
ebyrob,
Jeśli chodzi o „zmianę kontroli źródła” - prawie wszystkie współczesne systemy mogą przenosić historię jeden do drugiego, generować pliki zmian na poziomie poszczególnych projektów lub przy niewielkim wysiłku faktycznie osadzać swoje dzienniki zmian w pliku źródłowym (gdy staje się to właściwe w ruchu nie przed). Tak więc technologia istnieje, problemem są ludzie decydujący się nie korzystać z kontroli źródła.
ebyrob,
1

Jestem zaskoczony, że nikt o tym nie wspominał, ale czy nie jest to pierwotny powód, aby spełnić wymagania licencji? Oznacza to, że niektóre licencje mówią, że każda zmiana dokonana w pliku musi być odnotowana w samym pliku?

Sverre Rabbelier
źródło
1
które licencje tak mówią?
Trasplazio Garzuglio
2
Pracowałem w miejscu, w którym zgodność Sarbanes Oxley, w którą wierzyli, wymagała zmiany bloków w plikach źródłowych. Przez lata używali również PVCS (aka „Wymiary”), więc naprawdę nie mieli żadnej kontroli wersji, ale co ja wiedziałem?
Bruce Ediger
@Marco: Nie pamiętam, inaczej bym do niego link.
Sverre Rabbelier,
1
Wymaga tego sekcja 2a GPLv2. Większość projektów ignoruje to, niektóre mają pojedynczy plik „ChangeLog” (często generowany z ich VCS).
dsas
0

Powodem, dla którego nadal prowadzimy dziennik zmian w naszej sekcji komentarzy, jest łatwość użycia. Często podczas debugowania problemu łatwiej jest przewinąć do góry pliku i przeczytać dziennik zmian, niż otworzyć plik kontroli źródła, zlokalizować plik w nim i znaleźć wprowadzone zmiany

briddums
źródło
1
Osobiście uważam, że to trochę bolesne, gdy plik 200 linii ma długość 1000 linii z powodu dodania dziennika zmian do każdego pliku źródłowego. Ten dodatkowy hałas w rzeczywistości przesłania to, co ważne, wkrótce.
ebyrob,