Czy dobrą praktyką jest komentowanie numeru wydania?

Widziałem wiele numerów numerów z komentarzy kodu jQuery . (W rzeczywistości w kodzie jQuery było 69 numerów numerów.) Myślę, że to dobra praktyka, ale nigdy nie widziałem żadnych wytycznych.

Jeśli jest to dobra praktyka, jakie są wytyczne dla tej praktyki?

Zasadniczo nie uważałbym tego za dobrą praktykę. Ale w wyjątkowych przypadkach może być bardzo przydatny, a mianowicie gdy kod musi zrobić coś nieintuicyjnego, aby rozwiązać złożony problem, i bez żadnego wyjaśnienia istnieje ryzyko, że ktoś może chcieć „naprawić” ten dziwny kod, a tym samym go złamać , wyjaśniając uzasadnienie, powstałby ogromny komentarz, który powiela informacje z problemu.

Myślę, że wystarczy dodać numer problemu do komunikatu zatwierdzenia, gdy zatwierdzasz odpowiednią poprawkę w systemie kontroli źródła.

Na przykład:

Błąd nr 203: Połączenia z bazą danych nie przekraczają limitu czasu po 30 sekundach.

Uważam, że dodanie numerów problemów, nazw deweloperów lub dat, w których dokonano zmian w kodzie, po prostu zanieczyszcza bazę kodów i naprawdę powinno być zarządzane zewnętrznie przez system kontroli źródła.

Całkowicie nie zgadzam się z innymi plakatami tutaj!

Komentarze do kodu z referencjami śledzenia mogą być ogromną pomocą w programowaniu konserwacji.

Jeśli śledzę błąd i zbliżam się do obszaru kodu, aby zobaczyć, że został on ostatnio zmieniony, i odsyłam do kontekstu zmiany, jest to bóg.

Tak, mamy kontrolę kodu źródłowego, ale sprawdzanie plików i modułów indywidualnie może być dość powolne. Chcesz, żeby te rzeczy rzucały się na ciebie z powodu ostatnich zmian.

Prawdopodobnie byłbym przestarzały, ponieważ widzę naprawdę stare w bazie kodu, ale jest bardzo mało wady w utrzymywaniu nowszych i wiele potencjalnie zaoszczędzonego czasu programisty, jeśli używasz ich mądrze.

Właściwie uważam, że te małe odniesienia do twojego systemu śledzenia błędów są lepsze niż szczegółowe komentarze w kodzie.

Jeśli zgadzasz się z polityką „Czystego kodu”, prawdopodobnie musisz zadać sobie pytanie, czy dobrym pomysłem jest w ogóle dodawanie komentarzy. Jeśli kod można wyjaśnić tylko za pomocą komentarza, to oczywiście dodaj go, w przeciwnym razie powinieneś być w stanie łatwo zrozumieć, co robi twój kod po prostu czytając go (pod warunkiem, że używasz rozsądnych nazw dla swoich zmiennych, metod itp.).

Niezależnie od twojego osobistego poglądu na temat tego, czy komentowanie jest dobrą praktyką, komentarz powinien zawierać informacje, które mają bezpośrednią wartość dla kodu, do którego odnosi się komentarz. W takim przypadku pojawia się pytanie, czy dodanie numeru wydania dodaje wartości do kodu. Problem, który widzę przy dodawaniu numeru problemu, polega na tym, że możesz mieć sekcję kodu, którą można znacznie zmodyfikować w celu zaspokojenia kilku problemów, a po pewnym czasie niemożliwe będzie prawidłowe określenie, które zmiany związane są z konkretnym problemem. Późniejsze problemy mogą na przykład wymagać znacznej zmiany kodu związanego z poprzednimi problemami. Jest to być może skrajny przykład, jednak pokazuje, jak numery problemów w komentarzach w kodzie mogą okazać się całkiem bezużyteczne.

Jeśli mógłbyś zagwarantować, że sytuacja, którą właśnie opisałem, nigdy się nie wydarzy, nadal twierdzę, że sam numer problemu jest nadal całkiem bezużyteczny bez opisu tego, o czym jest problem, a jednak wszystkie te informacje naprawdę należą do twojego system śledzenia problemów i należy go zduplikować. Lepszym miejscem do odnotowania numeru problemu byłby twój system kontroli wersji jako komentarz do zatwierdzenia. Zaletą jest to, że możesz porównywać wersje i widzieć zmiany w kodzie związane z konkretnym problemem, a sam numer problemu zapewnia identyfikator potrzebny, aby sprawdzić przyczynę zmiany w kodzie.

Mając to na uwadze, sugeruję, że dodawanie numerów problemów do komentarzy w kodzie nie jest dobrą praktyką.

Myślę, że dobrą praktyką jest odwoływanie się do problemu do dalszego czytania, podając krótkie wyjaśnienie w samym komentarzu.

Generalnie dodaję komentarze tylko wtedy, gdy w tym fragmencie kodu jest coś subtelnego lub nieintuicyjnego. Ponieważ niektórych subtelnych problemów nie da się całkowicie wyjaśnić w kilku wierszach, a ja nie chcę dodawać dziesiątek wierszy komentarzy, dodam krótki komentarz opisujący, co to próbuje osiągnąć, i odsyłam do Detale.

Na przykład:

// Verify MAC before checking the padding, to avoid padding oracle attacks
// See issue 123 for details

Gdzie problem 123 opisuje, jak może wyglądać ten atak i dlaczego nowy kod jest odporny na atak.

Lub:

// Using foo's algorithm here, since it fits out usage pattern best
// Check issue 345 for a discussion of possible algorithms, and why foo was chosen.

Główny problem z umieszczaniem numerów problemów w źródle polega na tym, że masz teraz odniesienie zewnętrzne. Musisz więc mieć pewność, że nie stracisz problemu.

Umieszczenie numeru problemu w komunikatach zatwierdzenia może być bardzo przydatne, gdy kod źródłowy jest podłączony do ciągłej integracji. Aplikacje takie jak TeamCity wyciągną te informacje i umożliwią lepsze raportowanie.

W związku z powyższym nie jestem w 100% pewien, że wywodzi się z komentarzy do kodu. Umieszczanie numerów spraw w kodzie działa dobrze, jeśli numery problemów są utrzymywane (np. Nie zmieniasz śledzenia problemów) i nie masz wielu problemów dla danego projektu.

Prawdopodobnie jest to bardziej pomocne, jeśli opisujesz problem i rozwiązanie, aby następny programista nie musiał sprawdzać numeru problemu. Kompilator lub minimalizator po prostu usunie twoje komentarze, zanim kod zostanie wypuszczony na wolność, więc nie powinno to mieć wpływu na wynik końcowy.