Zostaliśmy poproszeni o dodanie komentarzy do tagów początkowych, końcowych, opisu, rozwiązania itp. Dla każdej zmiany, którą wprowadzamy do kodu w ramach naprawy błędu / implementacji CR.
Obawiam się, czy zapewnia to jakąś wartość dodaną? W tej chwili mamy wszystkie szczegóły w historii kontroli wersji, które pomogą nam śledzić każdą zmianę?
Ale moi przewodnicy nalegają, aby komentarze były „dobrą” praktyką programistyczną. Jednym z ich argumentów jest to, że CR należy zmniejszyć / zmienić, byłoby kłopotliwe, gdyby nie było komentarzy.
Biorąc pod uwagę, że zmiany byłyby w dużej mierze pomiędzy kodami, czy naprawdę pomogłoby dodanie komentarzy do każdej wprowadzanej przez nas zmiany? Czy nie powinniśmy pozostawić kontroli wersji?
version-control
bug
comments
change
Chillax
źródło
źródło
Użyj najlepszego narzędzia do pracy. Twój system kontroli wersji powinien być najlepszym narzędziem do rejestrowania błędów i CR: automatycznie rejestruje datę i osobę, która dokonała zmiany; nigdy nie zapomina dodać wiadomości (jeśli skonfigurowałeś ją tak, aby wymagała wiadomości zatwierdzania); nigdy nie zawiera adnotacji do niewłaściwej linii kodu lub przypadkowo usuwa komentarz. A jeśli twój system kontroli wersji już działa lepiej niż twoje komentarze, niemądrze jest powielać pracę dodając komentarze.
Czytelność kodu źródłowego jest najważniejsza. Baza kodu, która jest zaśmiecona komentarzami, zawierającymi pełną historię każdej poprawki i CR, wcale nie będzie bardzo czytelna.
Ale nie pomijaj komentarzy całkowicie: dobre komentarze (nie niewolnicze dokumentowanie każdego startu / stopu / opisu / rozwiązania każdej poprawki błędu i CR) zwiększają czytelność kodu. Na przykład w przypadku trudnego lub niejasnego fragmentu kodu, który dodajesz w celu naprawienia błędu, komentarz formularza
// fix ISSUE#413informujący ludzi, gdzie można znaleźć więcej informacji w narzędziu do śledzenia problemów, jest doskonałym pomysłem.źródło
fix ISSUE#413nie jest dobrym komentarzem w kodzie. Powinieneś być w stanie zrozumieć kod bez konieczności odwoływania się do dokumentacji zewnętrznej. Zamiast podawać losową liczbę, faktycznie wyjaśnij, dlaczego ta podstępna część kodu jest wymagana do robienia tego. Do tego służą komentarze: wyjaśnienie tych części kodu, które nie są oczywiste.fix ISSUE#413jest problem, w którym problem jest tak skomplikowany (skrajnie zależny od systemu operacyjnego i konfiguracji przypadek narożny lub wywołany tylko przez dane złych klientów), że jego odpowiednie opisanie wymagałoby kilka akapitów; tego typu sprawą lepiej zajmuje się moduł do śledzenia problemów IMO. Nawet wtedy krótki opis jest dobry.fix ISSUE#413jest całkowicie w porządku, a nawet preferowany, pod warunkiem, że zawiera także rozsądną ilość informacji na temat problemu nr 413. Samo podsumowanie raportu o problemie bez podania wskaźnika utrudnia życie przyszłemu czytelnikowi, który potrzebuje wszystkich szczegółów.fix ISSUE#413w komentarzu kompletność, ale nie używaj go jako kuli.Komentarze w kodzie dotyczą tego, czym jest kod w danym momencie. Wykonanie migawki w dowolnym momencie nie powinno odnosić się do starych (lub gorszych, przyszłych) wersji kodu.
Komentarze w VCS dotyczą zmian kodu. Powinny one czytać jako opowieść o rozwoju.
Czy każda zmiana powinna zawierać komentarze? w większości przypadków tak. Jedynym wyjątkiem, jaki sobie wyobrażam, jest to, że oczekiwane zachowanie zostało już udokumentowane, ale nie było to, co dostałeś, z powodu błędu. Naprawienie go powoduje, że istniejące komentarze są bardziej precyzyjne, więc nie trzeba ich zmieniać. Sam błąd powinien być udokumentowany w historii zgłoszenia i komentarzu do zatwierdzenia, ale tylko w kodzie, jeśli kod wygląda dziwnie. W takim przypadku
// make sure <bad thing> doesn't happenpowinno wystarczyć.źródło
Jeden rodzaj komentarza, który naprawdę doceniam to:
// To zaimplementowano dla reguły biznesowej 5 wniosku 2
lub cokolwiek do cholery używasz do zebrania swoich wymagań.
Ma to dwie zalety, jedną z nich jest to, że pozwala ci znaleźć powód, dla którego zaimplementowałeś dany algorytm bez wyszukiwania, a drugą jest to, że pomoże ci komunikować się z inżynierami niebędącymi programistami, którzy pracują / tworzą dokumenty wymagań.
Może to nie pomóc w przypadku mniejszych zespołów, ale jeśli masz analityków, którzy opracowują twoje wymagania, może być nieoceniony.
źródło
Twoje wskazówki mają rację, gdy mówią, że komentarze są dobrą praktyką programistyczną, jednak są wyjątki. Dodanie komentarza do każdej wprowadzonej zmiany jest jedną z nich. I masz rację mówiąc, że powinno to należeć do systemu kontroli wersji. Jeśli musisz przechowywać te komentarze w jednym miejscu, to VCS jest właściwym rozwiązaniem. Komentarze w kodzie źródłowym mają tendencję do starzenia się i są nieaktualne. Żadne komentarze nie są o wiele lepsze niż złe komentarze. To, czego nie chcesz, to komentarze w obu miejscach (w kodzie i VCS), które nie są zsynchronizowane. Celem jest utrzymanie stanu SUCHOŚCI poprzez posiadanie jednego źródła prawdy dla zmian w kodzie.
źródło
Oprócz tego, co powiedzieli inni, zastanów się, co się stanie, jeśli zmiana wywoła efekt falowania w całym systemie. Załóżmy, że refaktoryzujesz część podstawowego interfejsu w procesie implementacji żądania zmiany - ten rodzaj zmiany może łatwo dotknąć dużego odsetka plików kodu źródłowego w dowolnym nietrywialnym oprogramowaniu, co sprowadza się do trywialnych zmian (klasa lub zmiany nazwy metody). Czy powinieneś przejrzeć każdy plik dotknięty taką operacją, aby ręcznie dodać adnotację do takich komentarzy, zamiast polegać na tym, że VCS robi to wszystko automatycznie? W jednym przypadku patrzysz na nieco więcej niż pięć minut pracy przy użyciu dowolnego przyzwoitego narzędzia do refaktoryzacji, a następnie rekompilacji, aby upewnić się, że nic nie zepsuło się na kompilacji, podczas gdy drugi może łatwo przejść do pracy w ciągu jednego dnia. Dla jakiej konkretnej korzyści?
Zastanów się również, co się dzieje, gdy przenosisz części kodu. Jeden z programistów baz danych, z którymi pracuję, w dużej mierze „każda linia SQL powinna być opatrzona adnotacją o wersji, w której została zmieniona, i przygotujemy osobne historie wersji dla każdego pliku, ponieważ wtedy łatwiej będzie zobaczyć kto zmienił co, kiedy i dlaczego ”. Który działa trochę, jakoś w porządku, gdy zmiana jestw kolejności zmiany pojedynczych linii. Nie działa tak dobrze, gdy, tak jak ostatnio, aby naprawić poważny problem z wydajnością, rozbijasz części większego zapytania wprowadzając tabele tymczasowe, a następnie zmieniasz kolejność niektórych zapytań, aby lepiej dopasować nowy przepływ kodu. To prawda, że różnica w stosunku do poprzedniej wersji była w dużej mierze bez znaczenia, ponieważ informowała, że około dwie trzecie pliku uległo zmianie, ale komentarz dotyczący odprawy był również czymś w rodzaju „poważnej reorganizacji w celu rozwiązania problemów z wydajnością”. Kiedy spojrzałeś ręcznie na dwie wersje, było całkiem jasne, że duże części naprawdę były takie same, tylko się poruszały. (I zajęło omawianej procedurze przechowywanej od regularnego wykonywania ponad pół minuty, do kilku sekund. Do tego czasu
Z nielicznymi wyjątkami śledzenie zmian i odwoływanie się do problemów jest pracą VCS, IMNSHO.
źródło
Zwykle przestrzegam tej zasady: jeśli zmiana jest oczywista, a wynikowy kod nie budzi pytań, nie przywraca ani nie zmienia istotnie żadnego wcześniejszego zachowania w znaczący sposób - pozostaw to VCS śledzenie numerów błędów i innych informacji o zmianie.
Jeśli jednak nastąpi zmiana, która nie jest oczywista, zmienia logikę - szczególnie znacząco zmienia logikę wykonaną przez kogoś innego w nieoczywisty sposób - bardzo korzystne może być dodanie czegoś takiego: „ta zmiana polega na zrobieniu tego i że z powodu błędu # 42742 ". W ten sposób, gdy ktoś patrzy na kod i zastanawia się „dlaczego to jest? Wygląda to dziwnie”, ma przed sobą pewne wskazówki i nie musi przeprowadzać dochodzenia za pośrednictwem VCS. Zapobiega to również sytuacjom, w których ludzie przerywają zmiany innych, ponieważ znają stary stan kodu, ale nie zauważają, że został on zmieniony od tego czasu.
źródło
Komentarze związane z kontrolą wersji nie należą do pliku źródłowego. Dodają tylko bałaganu. Ponieważ prawdopodobnie muszą być umieszczone w tym samym miejscu (jak blok komentarzy na górze pliku), spowodują konflikty uciążliwe tylko dla komentarzy, gdy równoległe gałęzie zostaną połączone.
Wszelkie informacje śledzenia, które można wyciągnąć z kontroli wersji, nie powinny być powielane w treści kodu. Dotyczy to głupich pomysłów, takich jak słowa kluczowe kasowania RCS, takie jak
$Log$i podobne .Jeśli kod kiedykolwiek wykracza poza zakres systemu kontroli wersji, ten ślad komentarzy na temat jego historii traci kontekst, a zatem większą część jego wartości. Aby poprawnie zrozumieć opis zmiany, potrzebujemy dostępu do wersji, abyśmy mogli zobaczyć różnicę do poprzedniej wersji.
Niektóre stare pliki w jądrze Linuksa mają duże bloki komentarzy historii. Te pochodzą z czasów, gdy nie było systemu kontroli wersji, tylko tarballi i łatki.
źródło
Komentarze w kodzie powinny być minimalne i dokładne. Dodanie informacji o usterce / zmianie nie jest cenne. Powinieneś użyć do tego kontroli wersji. Jakiś czas Kontrola wersji zapewnia nieco lepszy sposób zmiany - używamy ClearCase UCM; Działania UCM są tworzone na podstawie numerów defektów, obszaru zmian itp. (Np. Defect29844_change_sql_to_handle_null).
W komentarzach do odprawy preferowane są szczegółowe komentarze.
Wolę podać szczegółowe informacje na temat podstawowych informacji, szczegóły rozwiązania NIE wdrożonego z powodu niektórych skutków ubocznych.
Pramagic Programmer i CleanCode prowadzi do następujących wskazówek
Zachowaj wiedzę niskiego poziomu w kodzie, do którego on należy, i rezerwuj komentarze dla innych wyjaśnień wysokiego poziomu.
źródło