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?
java
c#
programming-practices
code-quality
comments
Diego Alvarez
źródło
źródło
Odpowiedzi:
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:
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.
Historia jest przechowywana w kontroli źródła.
Ufasz również, że komentarz został napisany przez tę osobę.
How
komentarze 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.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.
Wszyscy autorzy (oprócz ciebie) są równie wiarygodni.
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.
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.
Tak. Najlepszy powód jak dotąd.
Jeśli naprawdę potrzebuję tych informacji, sprawdzę je w kontroli źródła.
W przeciwnym razie nie ma to znaczenia.
Komentarze powinny być opisem, dlaczego i tak coś robisz.
Komentarze NIE powinny opisywać działania kodu (chyba że algorytm nie jest oczywisty).
źródło
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 ;-)
źródło