Czy konieczne jest napisanie komentarza javadoc do KAŻDEGO parametru w sygnaturze metody?

Jeden z deweloperów w moim zespole uważa, że ​​konieczne jest napisanie komentarza javadoc do KAŻDEGO parametru w sygnaturze metody. Nie sądzę, aby było to konieczne, a nawet uważam, że może być szkodliwe.

Po pierwsze, uważam, że nazwy parametrów powinny być opisowe i samodokumentujące. Jeśli nie jest od razu oczywiste, do czego służą twoje parametry, prawdopodobnie robisz to źle. Rozumiem jednak, że czasami nie jest jasne, do czego służy parametr, więc w takich przypadkach tak, powinieneś napisać komentarz javadoc wyjaśniający parametr.

Ale myślę, że nie trzeba tego robić dla KAŻDEGO parametru. Jeśli jest już oczywiste, do czego służy parametr, komentarz javadoc jest zbędny; tworzysz dla siebie dodatkową pracę. Ponadto tworzysz dodatkową pracę dla każdego, kto musi utrzymywać Twój kod. Metody zmieniają się z czasem, a utrzymywanie komentarzy jest prawie tak samo ważne jak utrzymanie kodu. Ile razy widziałeś komentarz typu „X robi Y z powodu Z” tylko po to, aby zobaczyć, że komentarz jest nieaktualny, a w rzeczywistości metoda nie przyjmuje już parametru X? Dzieje się tak przez cały czas, ponieważ ludzie zapominają aktualizować komentarze. Twierdziłbym, że wprowadzający w błąd komentarz jest bardziej szkodliwy niż brak komentarza. A zatem istnieje niebezpieczeństwo przesadnego komentowania: tworząc niepotrzebną dokumentację, „

Szanuję jednak drugiego programistę w moim zespole i akceptuję, że być może ma on rację, a ja się mylę. Właśnie dlatego zadaję wam moje pytanie, koledzy deweloperzy: czy rzeczywiście konieczne jest napisanie komentarza javadoc dla KAŻDEGO parametru? Załóżmy, że kod jest wewnętrzny dla mojej firmy i nie zostanie wykorzystany przez żadną zewnętrzną stronę.

Adnotacje Javadoc (i słowem Microsoft XMLDoc) nie są komentarzami , lecz dokumentacją .

Komentarze mogą być tak rzadkie, jak chcesz; zakładając, że Twój kod jest w połowie czytelny, zwykłe komentarze są jedynie drogowskazami, aby pomóc przyszłym programistom w zrozumieniu / utrzymaniu kodu, na który patrzyli już od dwóch godzin.

Dokumentacja stanowi umowę pomiędzy jednostką kodu i jego rozmówców. Jest to część publicznego API. Zawsze zakładaj, że Javadoc / XMLdoc skończy albo w pliku pomocy, albo w wyskakującym oknie autouzupełniania / intellisense / uzupełniania kodu i będzie obserwowany przez osoby, które nie sprawdzają wewnętrznych elementów twojego kodu, ale po prostu chcą go użyć do jakiegoś celu ich własny.

Nazwy argumentów / parametrów nigdy nie są oczywiste. Zawsze myślisz, że są, kiedy spędziłeś ostatni dzień pracując nad kodem, ale spróbuj wrócić do niego po 2 tygodniach wakacji, a zobaczysz, jak bardzo są nieprzydatni.

Nie zrozum mnie źle - ważne jest, aby wybrać znaczące nazwy zmiennych i argumentów. Ale jest to problem dotyczący kodu, a nie dokumentacji. Nie traktuj dosłownie wyrażenia „samo dokumentowanie”; oznacza to w kontekście dokumentacji wewnętrznej (komentarze), a nie dokumentacji zewnętrznej (umowy).

Skomentuj wszystko lub nic nie komentuj (oczywiście komentowanie wszystkiego jest znacznie lepszym wyborem). Pomyśl o kimś, kto używa twojego kodu, albo przeglądając API bezpośrednio w pliku źródłowym lub w wygenerowanym pliku doc ​​(tj. Wyjściu doxygen). Niespójności zwykle prowadzą do zamieszania, co prowadzi do czasu spędzonego na przeszukiwaniu źródła, aby dowiedzieć się, dlaczego coś nie zostało skomentowane, co prowadzi do zmarnowanego czasu, którego można by uniknąć, gdyby parametr został skomentowany w pierwszej kolejności.

Pamiętaj: coś, co ma dla ciebie sens, może być interpretowane zupełnie inaczej przez kogoś innego, bez względu na to, jak przyziemna jest twoja opinia (pomyśl o kimś, kto nie jest tak silny w języku angielskim, czytając i próbując zrozumieć Twój kod).

Powiedziawszy to wszystko, jeśli drugi programista podkreśla znaczenie dokumentowania wszystkiego, to równie duży nacisk (jeśli nie więcej) należy na aktualizację dokumentacji. Jak już wspomniałeś, nie ma nic gorszego niż przestarzałe komentarze (tak samo złe, jeśli nie gorsze niż pominięte dokumenty).

Zacznijmy od założenia, że ​​cykle programistów są zasobem, który staramy się zachować.

Oznacza to, że deweloperzy nie powinni tracić czasu na dokumentowanie oczywistych parametrów i zwracanych wartości, prawda?

Rozbijmy to.

Jeśli wszystko udokumentujemy, zakładając, że komentarze krańcowe są naprawdę trywialne i nie wymagają żadnych przemyśleń ani badań, kosztem jest dodatkowy czas na wpisanie komentarza i poprawienie literówek.

Jeśli wybieramy i wybieramy, koszty są następujące:

• Posiadanie i wygranie kłótni z innymi programistami w zespole, którzy uważają, że wszystko należy udokumentować.
• Dla każdego parametru określanie, czy należy to udokumentować, czy nie.
• Więcej argumentów ze swoim zespołem, gdy ktoś ma inne zdanie na temat tego, czy parametr powinien zostać udokumentowany.
• Czas spędzony na szukaniu kodu i badaniu, kiedy okazuje się, że parametr, który został uznany za oczywisty, nie jest taki.

Byłbym skłonny po prostu dokumentować wszystko. Minusem jest wyraźny, ale jest zawarty.

Jeśli i tak piszesz Javadoc, równie dobrze możesz napisać go całkowicie, nawet uwzględniając „oczywiste” parametry. Mogą być oczywiste dla ciebie lub innego programisty, ale każdy, kto na to patrzy, skorzystałby na znajomości intencji każdego parametru.

Jeśli chodzi o prawidłowe utrzymanie Javadoc, musisz użyć narzędzi do rozwoju, które ci w tym pomogą. Przychodzi mi na myśl Eclipse . Oczywiście, jeśli jest to ważne, musisz upewnić się, że wszyscy członkowie zespołu robią wszystko, aby zachować kod, w tym komentarze.

Nie zapominaj, że javadoc może być widoczny bez oddzielnego kodu, czego najlepszym przykładem jest sam interfejs API Java . Nie włączając javadoc do każdego parametru w metodzie, wprowadzasz w błąd metodę i sposób jej użycia.

„konieczne” jest całkowicie subiektywne. Myślę, że pytasz: „w swojej sytuacji powinieneś dodać komentarz javadoc”. Nie znając zakresu ani kontekstu Twojej aplikacji, skąd mamy wiedzieć, co jest dla Ciebie odpowiednie?

Jeśli ten publiczny kod (tj. Kod przeznaczony dla innych, taki jak interfejs API), to tak, udokumentuj każdy parametr. Nie zakładaj, że czytelnik wie o projekcie tak samo jak ty. Ale w przeciwnym razie to od Ciebie i Twojego zespołu zależy podejmowanie własnych decyzji.