Jakie jest najlepsze podejście do komentarzy kodu wbudowanego?

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?

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).

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 ;-)