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ę.