Javadoc to nie dokumentacja!
2009-01-30
Ostatnio mam sporo kontaktu z Javą, a konkretniej JVM i bibliotekami pisanym w Javie. Co rusz powtarza się ten sam scenariusz: znajduję bibliotekę, zaglądam na jej stronę WWW, tam jest jednoakapitowy opis biblioteki. Często w opisie znajdują się informacje o tym, że biblioteka jest napisana w Javie, nowoczesnym obiektowym języku na platformie... [yadda yadda yadda]. Klikam w “Documentation” i dostaję zrzut API z javadoc.
Javadoc jest przekleństwem świata JVM, bo samo jego istnienie pozwala ludziom nie pisać dokumentacji. Ot, wystarczy kliknąć i jest dokumentacja! Proszę ile stron HTML się wygenerowało.
Zrzut API zrobiony javadoc tonie jest dokumentacja! Patrząc na listę często setek klas w żaden sposób nie domyślę się, do czego może mi posłużyć biblioteka, jak ogólnie się jej używa, jakie są podstawowe wzorce użycia. Nie zrozumiem też jak jest zorganizowana. Problem jest tym większy, że Java wymusza dodatkowe klasy, które nic nie wprowadzają do dziedziny problemu, za to komplikują kod. Ręka w górę kto widzi ciągle CośTamManager i CośTamManagerFactory.
Biblioteka, której jedyny opis istnieje w postaci zrzutu javadoc powinna być uważana za nie posiadającą dokumentacji. Równie dobrze mogę poczytać kod źródłowy.
Zgadzam się, że sam Javadoc/doxygen to nie jest wystarczająca dokumentacja, nie zgadzam się natomiast ze stwierdzeniem, że klasy typu "CośTamManager i CośTamManagerFactory" nic nie wnoszą do dziedziny problemu.
Użycie takich klas jest związane najczęściej z implementacją okreslonych wzorców projektowych, których zastosowanie pozwala na rozwiązanie problemu w czytelny i poprawny sposób. Java nie wymusza użycia wzorców projektowych, natomiast ich umiejętne stosowanie jest dobrą praktyką.
Ivan: ale przecież przyczyną powstania tych wzorców były ograniczenia Javy. Nie w każdym języku potrzebne są takie twory jak "fabryki" obiektów. Polecam np. http://norvig.com/design-patterns/, gdzie jest głębsza analiza wzorców z książki GoF.
Managerowie i fabryki nie mają nic wspólnego z dziedziną problemu: są elementem implementacji. Nie byłyby potrzebne, gdyby nie uwarunkowania implementacyjne, w tym przypadku Java.
Zgodzę się z autorem, że sama wygenerowana treść przy pomocy javadoc nie jest kompletną dokumentacją. Niemniej jednak z programistycznego punktu widzenia dobrze napisana dokumentacja kodu java w javadoc jest błogosławieństwem: przenoszenie się linkiem do klasy parametru albo pola innej klasy... Możliwość obejrzenia ciała metody, szczegółów co do działania bardzo pomaga. Dobry programista pisząc samą metodę stosuje trafną nazwę i stosuje się do konwencji javoskiej. Natomiast korzystanie z fabryk obiektów czy innych rzeczy wiąże się z wzorcami programowania. Możliwe, że zdają się być trudne w opanowaniu aczkolwiek prawie każdy framework korzysta z konwencji wzorcowej.
A ja się nie zgadzam. Jasne - jak ktoś nie pokomentuje funkcji i klas (nie napisze, co one robią, albo napisze to jednym zdaniem), to trudno to nazwać dokumentacją i równie dobrze można czytać kod źródłowy (chociaż jak jest chociaż po jednym zdaniu opisu, to już coś). Natomiast jeśli funkcje i klasy są bogato komentowane, z przykładami użycia i w ogóle (a widziałem takie), to to jest normalna dokumentacja. Może mogłaby mieć coś więcej, ale po co? Tak to przynajmniej wszystko jest ustandaryzowane, bo wymusza to javadoc (przynajmniej do pewnego stopnia). Co za różnica, czy napiszę osobną dokumentację z opisem działania i przykładami, czy zrobię to w komentarzach javadoc? Wychodzi na jedno.
Zgadzam się z przedmówcą, wszystko zależy od tego jak ktoś podszedł do pisania dokumentacji (wiąże się to także bezpośrednio z podejściem do komentowania kodu). Nie javadoc jest winny, tylko ludzie, którzy piszą "po łebkach". Jak najbardziej są Javadoc'i, które są bardzo "gęsto" i konkretnie opisane (Apache, Amazon) z przypadkami użycia, opisami pakietów itd. Jak chcesz zamiast zamiast API Amazon S3 czytać kod źródłowy, to proszę bardzo.. Nie zmienia to jednak faktu, że niektóre Javadoc'i są pisane trochę "na odwal się", ale to nie wina narzędzia, tylko rzemieślnika.
Dobrze napisane komentarze umożliwiają ogarnięcie kodu. Zrzut API wystarcza w 90% przypadków, te 10% - analizuje się problem w kodzie. Bardzo niedbale napisane - zgadzam się, ciężko się ogarnąć. Ale trzeba być imbecylem, żeby nie potrafić ogarnąć zrzutu API, mając pod ręką diagram UML (większość dobrych programów/bibliotek ma taki).