Witam
Ostatnio rozmyslalem troche nad dokumentacja kodu. Dokumentacja aplikacji jest tak samo wazna jak kod programu. Z tego co widze wiekszosc ludzi traktuje dokumentacje jako dodatek i najczesciej pisze ja na koniec projektu, co sprawia ze nie jest pelnowartosciowa. Uwazam ze dokumentacja powina byc integralna czescia aplikacji oraz powinna powstawac rownolegle z kodem.
Moje pytanie jest nastepujace: Czy ktos z Was ma doswiadczenie w dokumentowaniu kodu, mam jakis pomysl jak to zrobic, fajne linku, wskazówki, pomysł na wslasny skrypt? Czy tez uwazacie ze kod powinien sam sie dokumentowac?
Hmm, seeweer wie, że RDoc jest do generowania dokumentacji. Jemu chodziło raczej o sposób, jak napisać DOBRĄ dokumentację (np korzystając z RDoca).
Co zrobić, by nowi programiści nie mieli problemów z szybkim wejściem w kod -oczywiście czytelność kodu jest najważniejsza, ale milej jednak czyta się dokumentacje, niż źródła.
Chodzi o porady, na co zwrócić uwagę pisząc dokumentację, czego unikać. Sami wiecie, że niektóre gemy lub pluginy mają dokumentacje, ale słabą.
Możecie w sumie napisać też które rzeczy w rubym uważacie za fajnie udokumentowane, a które źle?
Serio, gdyby do każdego “klejnotu” była dokumentacja taka jak http://api.rubyonrails.com to wg. mnie możnaby mówić o dobrej dokumentacji.
Dla mnie dobra dokumentacja to dobry opis publicznego API biblioteki - z przykładami, z opisem wszystkich możliwych parametrów i przykłady ich wykorzystania, dobrym przykładem jest np. render.
Złym przykładem jest wg. mnie dokumentacja w stylu: “aby zobaczyć opis wykorzystania tej biblioteki zajrzyj do testów” - czasami się zdarzają takie kwiatki, niektórzy nie mają problemu z czytaniem dobrych testów ale to raczej hardcore IMHO.
Od czasu poznawania Capistrano, które w wielu momentach zmuszało do czytania kodu źródłowego i stamtąd dowiadywania się o funkcjonalności, sikam ze szczęścia jak widzę “zajrzyj do testów”.
def suma(a, b)
a + b
end[/code]
Metoda totalnie oderwana od rzeczywistości, chciałem tylko pokazać jak to u mnie wygląda. Moduly klasy bardziej złożone są opatrzone komentarzem na samym początku opisującym co się dzieje w tej klasie/module do czego służy i gdzie się z tego korzysta. Dodatkowo istnieje dokument opisujący całe api służące do komunikacji, wraz z jakimiś prostymi przykładami. Poza tym oczywiście testy. Ale bywa, że dokumentacja do ,metoda_a’’ to tylko ,#metoda_a’’. Według mnie można spokojnie korzystać z RDoca. Byle tylko dokumentacja była aktualna i opisana w zrozumiały sposób.
