Jakie jest najlepsze podejście do komentarzy kodu wbudowanego?

13

Dokonujemy refaktoryzacji do 20-letniej bazy kodu starszego typu i rozmawiam z kolegą na temat formatu komentarzy w kodzie (plsql, java).

Nie ma domyślnego formatu komentarzy, ale w większości przypadków ludzie robią coś takiego w komentarzu:

// date (year, year-month, yyyy-mm-dd, dd/mm/yyyy), (author id, author name, author nickname) and comment

proponowany format przyszłych i przeszłych komentarzy, który chcę:

// {yyyy-mm-dd}, unique_author_company_id, comment

Mój kolega mówi, że potrzebujemy tylko komentarza i musimy sformatować wszystkie wcześniejsze i przyszłe komentarze do tego formatu:

// comment

Moje argumenty:

  • Mówię ze względów konserwacyjnych, ważne jest, aby wiedzieć, kiedy i kto dokonał zmiany (nawet ta informacja znajduje się w SCM).
  • Kod jest żywy iz tego powodu ma swoją historię.
  • Ponieważ bez dat zmian nie można wiedzieć, kiedy wprowadzono zmianę bez otwarcia narzędzia SCM i wyszukiwania w długiej historii obiektów.
  • ponieważ autor jest bardzo ważny, zmiana autorów jest bardziej wiarygodna niż zmiana autora
  • Przyczyny zwinności, nie trzeba otwierać i poruszać się po narzędziu SCM
  • ludzie bardziej boją się zmienić coś, co ktoś zrobił 15 lat temu, niż coś, co niedawno stworzono lub zmieniono.
  • itp.

Argumenty mojego kolegi:

  • Historia znajduje się w SCM
  • Programiści nie mogą znać historii kodu bezpośrednio w kodzie
  • Pakiety mają 15 tys. Linii, a nieustrukturyzowane komentarze utrudniają ich zrozumienie

Jak myślisz, jakie jest najlepsze podejście? A może masz lepsze podejście do rozwiązania tego problemu?

Diego Alvarez
źródło
8
Naprawdę musisz nauczyć się funkcji winy / adnotacji / poklatkowego SCM. Dla każdej linii w pliku pokazuje, w której wersji ostatnio zmieniono linię. Nie trzeba przeszukiwać długiej historii.
Karl Bielefeldt,
FWIW, w którym pracuję, używamy trzeciego formatu (komentarz podstawowy) do zwykłych komentarzy opisowych, ale są zobowiązani do podania autora, daty i godziny oraz wyjaśnienia, gdy pojawią się poprawki do kodu. Jednak nie było zgody, kiedy to zostało wdrożone, z powodów wymienionych poniżej.
Robert Harvey,
2
Musisz ulepszyć proces SCM lub zestaw narzędzi. Programiści powinni bać się zmiany każdej linii, niezależnie od tego, ile ma lat.
Kirk Broadhurst
3
Zgadzam się w 100% z twoim kolegą
wim

Odpowiedzi:

32

Uwagi ogólne

Jestem wielkim zwolennikiem komentarzy, dlaczego (a nie jak) . Kiedy zaczynasz dodawać komentarze na temat tego, w jaki sposób wpadasz w problem, nic nie wymusza utrzymywania komentarzy w stosunku do kodu ( dlaczego zazwyczaj się nie zmienia (dlaczego wyjaśnienie może z czasem ulec poprawie)).

W ten sam sposób data / autorInfo nic nie zyskuje, jeśli chodzi o to, dlaczego kod został zrobiony w ten sposób; podobnie jak z czasem może się degenerować, ponieważ żadne narzędzia nie są egzekwowane. Również te same informacje są już przechowywane w systemie kontroli źródła (więc kopiujesz wysiłek (ale w mniej niezawodny sposób)).

Przechodząc przez argumenty:

Mówię ze względów konserwacyjnych, ważne jest, aby wiedzieć, kiedy i kto dokonał zmiany (nawet ta informacja znajduje się w SCM).

Dlaczego. Żadna z tych rzeczy nie wydaje mi się tak ważna dla utrzymania kodu. Jeśli musisz porozmawiać z autorem, znalezienie tych informacji z kontroli źródła jest stosunkowo proste.

Kod ma życie z tego powodu miał historię.

Historia jest przechowywana w kontroli źródła.
Ufasz również, że komentarz został napisany przez tę osobę. Howkomentarze z czasem ulegają degradacji, więc tego rodzaju historia staje się niewiarygodna. Z drugiej strony systemy kontroli źródła utrzymają bardzo dokładną historię i możesz dokładnie zobaczyć, kiedy komentarze zostały dodane / usunięte.

Ponieważ bez daty zmiany nie można wiedzieć, kiedy wprowadzono zmianę bez otwarcia narzędzia SCM i wyszukiwania w długiej historii obiektów.

Jeśli ufasz danym w komentarzu.
Jednym z problemów tego rodzaju jest to, że komentarze stają się niepoprawne w stosunku do kodu. Powrót do właściwego narzędzia dla zadania. System kontroli źródła zrobi to poprawnie bez potrzeby interwencji użytkownika. Jeśli twój system kontroli źródła jest uciążliwy, być może musisz nauczyć się, jak z niego lepiej korzystać (ponieważ ta funkcja jest zwykle łatwa), lub jeśli go nie obsługuje, znajdź lepszy system kontroli źródła.

ponieważ autor jest bardzo ważny, zmiana autorax jest bardziej wiarygodna niż zmiana autora

Wszyscy autorzy (oprócz ciebie) są równie wiarygodni.

Z powodu zwinności nie ma potrzeby otwierania narzędzia nawigacyjnego SCM

Jeśli narzędzie kontroli źródła jest uciążliwe, usychasz go nieprawidłowo lub (bardziej prawdopodobne) używasz niewłaściwego zestawu narzędzi, aby uzyskać dostęp do systemu kontroli źródła.

ludzie boją się zmienić coś, co ktoś zrobił 15 lat temu, niż coś, co zostało naprawdę zrobione ...

Jeśli kod trwał 15 lat, jest bardziej prawdopodobne, że będzie bardziej solidny niż kod, który trwał tylko 6 miesięcy bez potrzeby sprawdzania. Stabilny kod ma tendencję do pozostawania stabilnym, kod buggy z czasem staje się bardziej złożony (ponieważ przyczyną błędów jest to, że problem nie jest tak prosty, jak na pierwszy rzut oka).

Jeszcze więcej powodów do korzystania z kontroli źródła w celu uzyskania informacji.

Historia znajduje się w SCM

Tak. Najlepszy powód jak dotąd.

Programiści nie mogą znać historii kodu bezpośrednio w kodzie

Jeśli naprawdę potrzebuję tych informacji, sprawdzę je w kontroli źródła.
W przeciwnym razie nie ma to znaczenia.

Pakiety mają 15 000 linii i nieustrukturyzowane komentarze, które są trudniejsze do zrozumienia

Komentarze powinny być opisem, dlaczego i tak coś robisz.
Komentarze NIE powinny opisywać działania kodu (chyba że algorytm nie jest oczywisty).

Martin York
źródło
tks za twoją odpowiedź, jest wystarczająco dużo argumentów, aby zmienić mój punkt widzenia :)
Diego Alvarez
4
+1. Tylko jeden dodatek: o wiele trudniej jest skłamać kontroli źródła niż edytorowi tekstu (lub błędnemu typowi, lapseowi, czy cokolwiek innego).
tdammers
jeśli powiemy, że zaledwie osiem miesięcy temu zaczęliśmy używać narzędzi SCM dla plsql, a kod ma 20 lat, co myślisz, jeśli usuniemy autora i datę z historycznych komentarzy na temat zmian, których nie ma w SCM? to ma jakiś sens? czy w tej chwili nie ma sensu wiedzieć, kto i kiedy dokonano zmiany 15-20 lat temu? tks za czas i odpowiedź.
Diego Alvarez,
6

Zdecydowanie popieram twojego kolegę. Nie obejdziesz się bez spojrzenia na SCM, jeśli chcesz zrozumieć, dlaczego coś zostało zmienione, chyba że zachowasz stary kod w komentarzu.

Jeśli kod jest zbyt skomplikowany, aby go zrozumieć bez pisania ton komentarzy, sugeruję zainwestowanie energii w refaktoryzację, aby kod był czytelny / łatwy do utrzymania bez mnóstwa komentarzy.

W końcu zatrudniasz programistów, a nie opowiadaczy ;-)

Axel
źródło