Czy dobrze jest przechowywać komentarze dotyczące błędów w kodzie?

Mój zespół używa jasnego przypadku jako kontroli wersji. Projekt, nad którym pracuję, nie rozpoczął się 7-8 lat temu. Przez cały czas trwania projektu mieliśmy kilka wydań poprawek błędów Service Pack itp. Problemy są śledzone za pomocą systemu śledzenia błędów, a większość osób, które pracują nad poprawkami błędów, postępuje zgodnie z procedurą dołączania komentarza do START / Blok END z datą, autorem, identyfikatorem błędu itp.

Wydaje mi się, że jest to zupełnie nieistotne i sprawia, że ​​kod jest zagracony i trudny do utrzymania, i to są rzeczy, które muszą być częścią komentarzy / etykiet odpraw itp., W których możemy przechowywać dodatkowe informacje o cyklu życia produktu pracy.

Jaka jest najlepsza praktyka, której należy przestrzegać?

Niektórzy recenzenci kodu nalegają na komentarze na temat błędu i poprawki, aby ułatwić im życie. W moim rozumieniu muszą przejrzeć pliki, mapując je do widoku i uzyskać dziennik zmian gałęzi i przejrzeć go. Przydałoby się kilka sprawdzonych metod przesyłania zaktualizowanego kodu do przeglądu.

Problem z dodaniem poprawki jako komentarza do kodu polega na tym, że nie otrzymujesz pełnej historii. Jeśli zobaczę idealnie dobry fragment kodu oznaczony jako „jest to poprawka do bla bla ”, moją pierwszą reakcją byłoby powiedzenie „co z tego?”. Kod jest tam, działa. Jedyne, co muszę wiedzieć, aby zachować kod, to komentarz, który mówi mi, co robi.

Lepszą praktyką byłoby dodawanie odwołań do błędów w dziennikach zatwierdzania SCM. W ten sposób zobaczysz, czym jest błąd, gdzie został wprowadzony i jak został naprawiony. Ponadto, kiedy nadejdzie czas wydania, możesz po prostu wyodrębnić dzienniki SCM i dodać punktor informujący, że wystąpił błąd i został on naprawiony. Jeśli inna gałąź lub wersja wprowadza ten sam błąd, łatwo jest zlokalizować poprawkę i zastosować ją ponownie, jeśli rzeczywiście jest to ta sama rzecz.

Powiedziawszy to wszystko, zgadzam się również z odpowiedzią Charlesa. Jeśli przyczyna kodu nie jest oczywista, należy poinformować opiekuna, że ​​kod istnieje z jakiegoś powodu i należy go traktować ostrożnie.

Głównie zła praktyka. Nie powiem, że nigdy nie należy tego robić. Czasami napotykasz na błąd w zewnętrznym interfejsie API, który musisz obejść. Obejście problemu może wyglądać na zupełnie martwe, jeśli nie wiesz o podstawowej usterce. W takim przypadku dobrym pomysłem może być udokumentowanie błędu w kodzie, aby współpracownicy lub późniejsze osoby nie próbowały „naprawiać” oczywistego martwego kodu.

Zła praktyka. Komentarze będą nieaktualne i zaśmiecą kod. W razie potrzeby informacje są nadal dostępne w historii wersji systemu SCC.

Brzmi jak zła praktyka. Co jeśli Twoja organizacja zdecyduje się na migrację do innego systemu śledzenia błędów? Nie przywiązuj produktu zbyt mocno do aktualnie używanych narzędzi. Zamiast odwoływać się do konkretnych identyfikatorów błędów, a przyczyny, dla których kod wygląda tak, jak jest, są niejasne, uzasadnij swoją decyzję projektową komentarzami w kodzie.

Moją pierwszą reakcją byłoby nie powtarzanie się, więc wyjmij to z kodu i do dzienników SCM. Przeprowadziliśmy podobną dyskusję tutaj na temat komentarza do rewizji funkcji, nazwisk autorów oraz dat utworzenia plików i funkcji. W przeszłości (przed użyciem SCM) wszystkie te informacje były przechowywane w plikach, aby móc odtworzyć ewolucję pliku.

Około połowa programistów chce, aby te informacje mogły mieć wszystkie informacje w jednym miejscu (powoduje to, że szukają zmian w SCM). Druga połowa programistów nie rozpoczyna poszukiwań wskazówek co do zmian w kodzie, ale z SCM, więc nie potrzebują informacji w kodzie. Musimy jeszcze podjąć decyzję, co zrobić z tymi komentarzami. To bardzo zależy od sposobu, w jaki ludzie pracują, a niektórzy ludzie są bardzo uparci, aby porzucić swoje znane metody. To samo dotyczy komentowania bloku kodu i pozostawiania ich w kodzie na zawsze.

Żeby dodać do tego, co Dyaster i in. powiedziałem, chociaż JIRA ma naprawdę fajne możliwości wyświetlania zmian związanych z poprawkami błędów, absolutnie najlepszym miejscem do udokumentowania poprawki jest przypadek testowy. Jeśli kod nie jest jasny bez komentarza wskazującego, który błąd został naprawiony, oznacza to „zapach kodu”. To powiedziawszy, jeśli nie masz czasu na usunięcie zapachu, komentarz powinien odnosić się do przypadku testowego, gdzie powinno być o wiele bardziej oczywiste, dlaczego kod robi to, co robi. Jeśli nie masz czasu na napisanie instrukcji testowej wyjaśniającej naprawę błędu, oznacza to, że błąd nie został jeszcze naprawiony, został tylko odłożony.

Zgodziłbym się na dodanie identyfikatorów błędów w komunikatach zatwierdzania, a nie w samym kodzie. Bardzo przydatne są narzędzia do śledzenia błędów, które automatycznie zgarniają komunikaty zatwierdzania dla identyfikatorów błędów.

Ponadto można użyć polecenia blame / annotate / praise w systemie kontroli wersji, aby zastąpić te komentarze. Następnie, gdy uruchomisz coś takiego:

vcs blame file.ext

możesz zobaczyć przydatne informacje, zwykle w tym kto zmienił każdą linię, kiedy ją zmienił, oraz identyfikator zatwierdzenia. Z identyfikatora zatwierdzenia można uzyskać pełną wiadomość, która powinna zawierać identyfikator błędu.

Dobre systemy VCS pozwolą ci zignorować białe znaki podczas obliczania, kto zmodyfikował linię.

Nie wiem, co ma Clear Case dla tej funkcji.