Zazwyczaj uważam takie komentarze za złą praktykę i myślę, że tego rodzaju informacje należą do dzienników zatwierdzania SCM. W większości przypadków sprawia to, że kod jest trudniejszy do odczytania.
Jednakże , nadal często zrobić coś takiego dla określonych rodzajów zmian.
Przypadek 1 - zadania
Jeśli używasz środowiska IDE, takiego jak Eclipse, Netbeans, Visual Studio (lub masz jakiś sposób na wyszukiwanie tekstu w bazie kodu za pomocą czegokolwiek innego), być może twój zespół używa określonych „tagów komentarzy” lub „tagów zadań”. W takim przypadku może to być przydatne.
Od czasu do czasu podczas przeglądania kodu dodaję coś takiego:
// TOREVIEW: [2010-12-09 haylem] marking this for review because blablabla
lub:
// FIXME: [2010-12-09 haylem] marking this for review because blablabla
Używam do tego różnych niestandardowych tagów zadań, które widzę w Eclipse w widoku zadań, ponieważ posiadanie czegoś w dziennikach zatwierdzeń jest dobrą rzeczą, ale niewystarczającą, gdy na spotkaniu przeglądowym ktoś pyta cię, dlaczego poprawka XY została całkowicie zapomniana i prześlizgnął się. Tak więc w pilnych sprawach lub naprawdę wątpliwych fragmentach kodu służy to jako dodatkowe przypomnienie (ale zwykle skracam komentarz i sprawdzam dzienniki zatwierdzeń, ponieważ właśnie po to jest przypomnienie, więc nie zaśmiecam też kodu wiele).
Przypadek 2 - łaty Libs stron trzecich
Jeśli mój produkt musi spakować fragment kodu innej firmy jako źródło (lub bibliotekę, ale przebudowany ze źródła), ponieważ z jakiegoś powodu musiał zostać załatany, dokumentujemy łatkę w osobnym dokumencie, w którym wymieniliśmy te „zastrzeżenia” do wykorzystania w przyszłości, a kod źródłowy zwykle zawiera komentarz podobny do:
// [PATCH_START:product_name]
// ... real code here ...
// [PATCH_END:product_name]
Przypadek 3 - nieoczywiste poprawki
Ten jest nieco bardziej kontrowersyjny i bliższy temu, o co prosi twój starszy programista.
W produkcie, nad którym obecnie pracuję, czasami (zdecydowanie nie jest to coś powszechnego) mamy komentarz:
// BUGFIX: [2010-12-09 haylem] fix for BUG_ID-XYZ
Robimy to tylko wtedy, gdy poprawka nie jest oczywista, a kod jest odczytywany nienormalnie. Może tak być na przykład w przypadku dziwactw przeglądarki lub niejasnych poprawek CSS, które należy wdrożyć tylko dlatego, że w produkcie występuje błąd dokumentu. Ogólnie rzecz biorąc, chcielibyśmy połączyć go z naszym wewnętrznym repozytorium problemów, które następnie będzie zawierało szczegółowe uzasadnienie poprawki i wskazówki do dokumentacji błędu zewnętrznego produktu (powiedzmy, poradę bezpieczeństwa dla znanej wady Internet Explorera 6 lub coś w tym stylu).
Ale jak wspomniano, jest to dość rzadkie. A dzięki tagom zadań możemy regularnie je przeglądać i sprawdzać, czy te dziwne poprawki nadal mają sens lub czy można je wycofać (na przykład, jeśli porzuciliśmy obsługę wadliwego produktu powodującego błąd).
To właśnie w: przykład z prawdziwego życia
W niektórych przypadkach jest to lepsze niż nic :)
Właśnie natrafiłem na ogromną klasę obliczeń statystycznych w mojej bazie kodu, w której komentarz nagłówka miał postać dziennika zmian ze zwykłym yadda yadda: recenzent, data, identyfikator błędu.
Na początku myślałem o złomowaniu, ale zauważyłem, że identyfikatory błędów nie tylko nie zgadzają się z konwencją naszego obecnego narzędzia do śledzenia problemów, ale także nie pasują do tego, z którego korzystałem, zanim dołączyłem do firmy. Próbowałem więc przeczytać kod i zrozumieć, co robi klasa (nie będąc statystyką), a także próbowałem wykopać te raporty błędów. Zdarzyło się, że były one dość ważne i miałyby kłopot z życiem następnego faceta, aby edytować plik, nie wiedząc o nich dość okropnie, ponieważ zajmował się drobnymi problemami z precyzją i specjalnymi przypadkami opartymi na bardzo specyficznych wymaganiach wydawanych przez pierwotnego klienta . Ostatecznie, gdyby ich tam nie było, nie wiedziałbym. Gdyby ich tam nie było, a ja lepiej zrozumiałbym klasę,
Czasami trudno jest śledzić bardzo stare wymagania, takie jak te. Ostatecznie to, co zrobiłem, to nadal usuwanie nagłówka, ale po skradnięciu się w bloku komentarza przed każdą obciążającą funkcją opisującą, dlaczego te „dziwne” obliczenia są konkretnymi żądaniami.
W takim razie nadal uważałem to za złą praktykę, ale chłopcze, byłem szczęśliwy, że oryginalny twórca przynajmniej je zastosował! Lepiej byłoby zamiast tego wyraźnie skomentować kod, ale wydaje mi się, że było to lepsze niż nic.