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

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.

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.

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.

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.

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.

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.

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.

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!”.

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.

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.

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.

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?

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