dokumentacja kodu: kompletny przewodnik dla początkujących
jesteś trochę drogi do swojej pierwszej pracy programistycznej, a rzeczy są coraz łatwiejsze. Na początku cały kod, z którym miałeś do czynienia, mógł cię przytłoczyć i zdezorientować, ale zaczynasz go rozumieć. To świetnie! Teraz zastanawiasz się, jak przenieść napisany kod na wyższy poziom. Chociaż istnieje wiele rzeczy do nauczenia się o stosie programowania, z których wiele uczyni cię lepszym programistą, jest kilka, które będą ci służyć bez względu na to, na jakim stosie pracujesz. Jednym z nich jest dokumentacja kodu.
wielu programistów nie pisze wystarczająco dużo dokumentacji, albo dlatego, że nie widzą wartości, albo dlatego, że czują, że nie mają czasu. Nie musisz być jednym z tych programistów. Przy odrobinie czasu i dużej praktyce możesz dodać dokumentację dla swojego kodu, która sprawi, że czytanie go będzie przyjemnością zarówno dla Ciebie, jak i dla każdego, kto się pojawi.
dobra dokumentacja występuje w wielu formach
kiedy większość programistów myśli o dokumentacji kodu, myślą o komentarzach. Komentarze mogą być cennymi dodatkami do kodu, ale nie są jedyną definicją dokumentacji. Dokumentacja to wszystko, co piszesz oprócz kodu, aby pomóc komuś innemu zrozumieć, jak to działa. Możesz nie myśleć o tym w ten sposób, ale dobrym przykładem dokumentacji kodu jest plik README. Dobrym przykładem podstawowej dokumentacji jest Express.plik JS README. Odpowiada na kilka ważnych pytań dotyczących frameworka i mówi, jak możesz włączyć go do swojego projektu, jak go zainstalować i jak uruchomić testy.
dobra dokumentacja może również przybrać formę dokumentacji API. Jeszcze raz, Express.js stanowi świetny przykład. Ta wersja dokumentacji jest bardziej biblioteką referencyjną dla programistów korzystających z frameworka. Znajdziesz tu odpowiedzi na pytania o to, co robią poszczególne funkcje i co oznaczają różne parametry dla tych funkcji. Bez takiej dokumentacji jakościowej Express nie korzystałby z niej tak wielu zespołów, jak oni.
i oczywiście możesz używać komentarzy w wierszu do dokumentowania kodu. Tego rodzaju komentarze zwykle nie są używane, aby uczyć ludzi spoza twojego zespołu o kodzie. Zamiast tego są przydatne do wyjaśnienia kolegom z drużyny lub przyszłemu jaźni, co dzieje się w danym fragmencie kodu.
dlaczego powinieneś dokumentować swój kod
jak wspomniano powyżej, wielu programistów nie rozumie celu dokumentacji kodu. Będą twierdzić, że dobry kod powinien być samodokumentujący i że nie trzeba go wyjaśniać. Ci ludzie są, jednym słowem, w błędzie. Prawda jest taka, że dobra dokumentacja jest istotną częścią każdej podstawy kodu. Dlaczego? Ponieważ ludzie nie powinni czytać całego kodu, aby zrozumieć, co on robi. “Ludzie”w tym poprzednim zdaniu mogą odnosić się do każdego, w tym do Twojego przyszłego ja.
prawda jest taka, że często “ludzie”, którzy będą musieli zrozumieć kod po jego napisaniu, to Ty. Ta odrobina logiki, która wydawała się tak mądra, gdy pisałeś ją pół roku temu, może być dziś trudna do zrozumienia. Jeśli twój kod jest dobrze udokumentowany, nie musisz tracić czasu na zrozumienie, co robi. Będziesz mógł poświęcić kilka sekund na przeglądanie opisu, a następnie wrócić do tego, nad czym teraz pracujesz.
jeśli masz szczęście pracować nad kodem używanym przez dziesiątki lub setki programistów, dobra dokumentacja jest jeszcze ważniejsza. Życie Twoich użytkowników zostanie znacznie poprawione dzięki Twojemu czasowi poświęconemu na pisanie dobrej dokumentacji, a oni ci za to podziękują. Dosłownie!
kluczem do zapamiętania jest to, że dobra dokumentacja oszczędza więcej czasu niż potrzeba na jej napisanie. Może to być twój czas, może to być czas członków zespołu, a nawet ludzi, których nigdy nie spotkasz. Czasami pisanie dokumentacji pomoże ci nawet rozpoznać część kodu, która jest zbyt skomplikowana, abyś mógł ją uprościć.
niektóre typowe błędy dokumentacji
jako młodszy programista będziesz musiał poświęcić czas na naukę, co sprawia, że dokumentacja jest skuteczna. Dobrą wiadomością jest to, że możesz uczyć się od ludzi, którzy byli przed tobą, aby uniknąć typowych błędów.
Under-Documentation
jednym częstym błędem, który widzę w dokumentacji kodu, jest dokumentowanie informacji, które są już wyraźnie widoczne. Na przykład leniwi Programiści dodają “dokumentację” do funkcji, dodając blok, który zawiera nazwę funkcji, a także nazwy każdego parametru i ich poszczególnych typów. Ten rodzaj dokumentacji jest bezużyteczny! To trwa kilka sekund, aby ktoś odczytał nazwę funkcji i parametry, których potrzebuje. To nie dokumentacja, to tylko powtarzanie. Zamiast tego dokumentacja powinna zawierać krótki fragment informacji o tym, co robi funkcja i jak każdy parametr zmienia jej zachowanie lub dlaczego jest potrzebna.
nadmierna dokumentacja
odwrotny wzorzec może być również poważnym problemem. Aby uniknąć pisania zbyt małej dokumentacji, niektórzy programiści lubią pisać Wyjaśnienie dla każdego drobnego fragmentu logiki zawartej w funkcji. Skrupulatnie dokumentują wszystkie przesłanki, które doprowadziły do stworzenia tej funkcji. Zanim skończą, mogą spędzić tyle czasu na pisaniu funkcji, co na pisaniu dokumentacji. Co gorsza, dokumentacja jest często trudna do zrozumienia i trwa tak długo, jak czytanie kodu. Taka dokumentacja to również strata czasu. Zamiast tego, dobra dokumentacja daje podstawowe Wyjaśnienie zarówno tego, co i dlaczego. Jeśli są jakieś szczególnie trudne do zrozumienia części kodu, to dokumentacja powinna wyjaśnić tylko te części.
opierając się na testach, aby udokumentować
czasami natkniesz się na kogoś, kto twierdzi, że najlepszą formą dokumentacji są testy jednostkowe. Takie podejście ma poważną wadę: czytanie testów jednostkowych jest często tak samo trudne do wykonania, jak czytanie samego kodu. Każdy programista, który chce dowiedzieć się, co robi twój kod, będzie miał duży pierwszy krok, podczas gdy poluje i czyta wszystkie twoje testy jednostkowe. Wielu po prostu się podda, zanim osiągnie to, co zamierzało zrobić. Chociaż testowanie jednostkowe jest cennym dodatkiem do każdej bazy kodu, nie zastępuje dobrej dokumentacji.
sposoby przeniesienia dokumentacji na wyższy poziom
jeśli pracujesz na dużej bazie kodu, dokumentacja kodu może być zniechęcająca, zwłaszcza jeśli do tej pory nie byłeś sumienny w dokumentowaniu kodu. Może się wydawać, że próbujesz zagotować ocean. Jeśli masz dużą bazę kodu lub taką, w której dobra dokumentacja ma kluczowe znaczenie, możesz zbadać zautomatyzowane narzędzia do dokumentacji kodu. Narzędzia te znacznie upraszczają proces pisania spójnej, dobrej dokumentacji dla całego zespołu. Narzędzie takie jak GhostDoc inteligentnie spojrzy na Twój kod i użyje szablonów utworzonych przez twój zespół, aby uruchomić dokumentację za pomocą kilku naciśnięć klawiszy. Zautomatyzowane narzędzia do dokumentacji usuwają jeden z najczęstszych powodów sprzeciwu wobec pisania dokumentacji: zajmuje to zbyt dużo czasu.
po uzyskaniu spójnej dokumentacji Inne narzędzia umożliwiają łatwe udostępnianie tej dokumentacji. Zautomatyzowane narzędzia do dokumentacji eliminują ból związany z tworzeniem dobrej dokumentacji dla takich rzeczy, jak publiczne interfejsy API, które udostępnia Twój kod.
zacznij już dziś
pisanie świetnej dokumentacji jest o wiele łatwiejsze niż pisanie kodu. W przeciwieństwie do kodu, dokumentacja nie jest przedsięwzięciem typu “wszystko albo nic”. Zacznij od celu, aby codziennie pisać dobrą dokumentację dla jednej funkcji. Taka praktyka buduje zdrowe nawyki,a zyskasz, gdy poświęcisz dużo mniej czasu na zrozumienie części kodu. Z czasem zacznie się wydawać źle, gdy napiszesz kod, który nie ma dobrej dokumentacji. Zaczniesz wskazywać współpracownikom sposoby ulepszania dokumentacji podczas przeglądu kodu. Jeden mały nawyk poprawi kod Twojego zespołu dla całej firmy.
dowiedz się, jak GhostDoc może pomóc w uproszczeniu komentarzy XML, tworzeniu i utrzymywaniu wysokiej jakości dokumentacji pomocy.
o autorze
Eric Boersma
Eric Boersma jest programistą i menedżerem ds. rozwoju, który zrobił wszystko, od bezpieczeństwa IT w farmaceutykach po pisanie oprogramowania wywiadowczego dla rządu USA po budowanie międzynarodowych zespołów programistycznych dla organizacji non-profit. Uwielbia rozmawiać o rzeczach, których nauczył się po drodze, a także lubi słuchać i uczyć się od innych.
