wartość dokumentacji kodu

dokumentacja kodu jest zbiorem łatwych do zrozumienia obrazów i pisemnych opisów, które wyjaśniają, co robi baza kodu i jak może być używana.

mogą to być proste komentarze wyjaśniające powyżej funkcji i bloków, lub pełnoprawny Podręcznik programisty, wraz z nakazowymi stylami nakazów i zakazów, przeglądami każdej części aplikacji i podejściami do najczęstszych typów zadań kodowania.

często najlepiej jest znaleźć szczęśliwe medium między tymi dwoma skrajnościami, kiedy podejmujesz świadomą decyzję o skomentowaniu kodu i zarysowaniu bardziej gnarlier obszarów bazy kodu w prostym języku.

po co dokumentować swój kod?

po co zadawać sobie trud pisania o kodzie, zamiast po prostu pisać kod? Czy to nie byłoby bardziej produktywne?

Mental Save Points

dokumentacja jest jak mental save points dla tych czasów, kiedy w końcu masz to, co dzieje się pod koniec dnia i nie chcesz stracić rozpędu. Dobrze udokumentowany kod zapewni, że gdy będziesz musiał nurkować jutro rano (lub za kilka miesięcy), nie będziesz musiał poświęcać tyle czasu na przygotowanie się do pracy.

udokumentowany kod zostaje ponownie użyty

różnica między używaną biblioteką a nieużywaną biblioteką często sprowadza się do jej dokumentacji.

kto chce korzystać z nieudokumentowanej biblioteki open-source lub przyczynić się do nieudokumentowanego projektu? Prawie nikt.

w większości przypadków wolisz używać mniej wydajnej biblioteki z dokumentami. Dlaczego? Ponieważ dokumentacja przekazuje inne informacje o bazie kodu. Deweloperzy uważają, że projekt jest wart czasu i energii, aby napisać o nim w prostym języku, aby każdy, kto może być zainteresowany, mógł szybko zacząć i dowiedzieć się, jak to działa i dlaczego podjęto kluczowe decyzje.

znalezienie nowego, interesującego i dobrze udokumentowanego projektu w Twoim ulubionym języku może być bardzo ekscytujące i zabawne. Spójrzmy na ekstremalną alternatywę: konieczność użycia nieudokumentowanej biblioteki kodu i potencjalnie przyczynienia się do pozornie bizantyjskiej bazy kodu… brzmi boleśnie, prawda?

więc dlaczego nie udokumentowałeś własnego kodu?

dokumentowanie kodu jest częścią pisania dobrego kodu

podstawą dobrego kodu jest łatwość utrzymania, osiągana poprzez zrozumiałą i czytelną dokumentację.

istnieje wiele sposobów dokumentowania kodu:

• wybór dobrych nazw dla zmiennych i funkcji
• pozostawienie krótkich komentarzy w kodzie, aby pomóc w nadaniu kontekstu przyszłym czytelnikom
• dodawanie ilustracyjnych obrazów, takich jak diagramy zależności sekwencji i encji
• dostarczanie dokumentów API, opisujących każdą klasę, metodę, argument i wartość zwracaną
• przy użyciu statycznie wpisanego języka, takiego jak TypeScript (TypeScript). typy jako dokumentacja)

Porównaj dwa przykłady

Załóżmy, że pobierasz dane z interfejsu API zaplecza i „ingresujesz” je-przekształcając je w bardziej użyteczny kształt dla interfejs użytkownika front-end. Oto pierwsze z dwóch możliwych rozwiązań.

// wdgt.jsexport const converter = (w) => { wdgtHdr = { name: w.nm, id: w.id, ts: w.lastTS } wdgtDtl = { dtlId: w.dtlId, dtlName: w.dtlNm, openTS: w.oTS, closeTS: w.cTS } wdgtRev = w.revs.map((r) => { const { note, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS } = r const rr = { assocId: prsn1Id, assoc: `${prsn1Fn} ${prsn1Ln}`, amount: amt, note: note, revTS: cTS, } return rr } return { wdgtHdr, wdgtDtl, wdgtRev }}

powyższy kod może być bolesny. Po nazwie widać, że jest to jakiś konwerter, który przyjmuje w jako swój param.

wygląda na to, że zwraca nagłówek, może szczegóły i coś o nazwie revs. Skąd się wzięły obroty? Oczywiście nie ma szczegółów na temat przychodzących nazw zmiennych note, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS… a może jest? Czy rr to skrót od returned rev? Kto wie.

spójrzmy na drugi przykład.

// widget_utils.ts// widgetConverter :: widgetRespDTO -> widgetexport const widgetConverter = (wResp: widgetRespDTO): Widget => { const widgetHeader: WidgetHeader = { name: wResp.nm, id: wResp.Id, ts: wResp.lastTS), // timestamp } const widgetDetail: WidgetDetail = { id: wResp.widgetId, name: wResp.dtlNm, openTS: wResp.oTS, // timestamp closeTS: wResp.cTS // timestamp } // is nested inside of WidgetRespDTO // .map -> const widgetRevisions: ReadonlyArray<WidgetRevision> = wResp.revs.map((wRevs: WidgetRevisionsRespDTO): WidgetRevision => { // how that other team names their variables...! const { cmt, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS } = wRevs const comment: string = cmt const associateId: string = prsn1Id const associateName: string = `${prsn1Fn} ${prsn1Ln}` const amount: number = amt const revisionTS: number = cTS // unix timestamp, and "closeTS" fyi return { associateId, associateName, amount, comment, revisionTS, } } return { widgetHeader, widgetDetail, widgetRevisions, }}

co za różnica! Ta funkcja znajduje się w pliku util, więc główny plik jest już mniej zaśmiecony. Jest również napisany w maszynopisie zamiast zwykłego JavaScript, więc mamy korzyści z definicji typów, które mogą nam pomóc.

konwertujemy widgetRespDTOs na widget S. choć skrócone, mamy pełną wiedzę na temat tego, czym jest wResp. Tworzymy widgetHeader i widgetDetail, które łatwo zobaczyć. Rozumiemy również, czym są oTS i cTS. Możemy powiedzieć, że WidgetRevisionsRespDTOS są zagnieżdżone wewnątrz WidgetRespDTO.

ktoś bardzo uprzejmie zmienił nazwę przychodzących zmiennych, więc każdy, kto widzi ten kod, wie, czym one są. Na koniec widzimy, że Widget musi składać się ze zwracanego obiektu {widgetHeader, widgetDetail, widgetRevisions}, ponieważ musi pasować do zwracanego typu Widget podanego na górze.

z jakiego kodu korzystałbyś lepiej?

kto korzysta?

dobrze udokumentowany kod przynosi korzyści wielu osobom:

młodsi Programiści

ponieważ jest on prosty i łatwy do zrozumienia, dokumentacja pomaga młodszym programistom i nowym członkom zespołu czuć się pewnie, wskakując do bazy kodu. Zapobiega to frustracji i wczesnej rezygnacji z zadania, ponieważ zbyt szybko się komplikuje.

pomocny jest również dla młodszych programistów pisanie własnej dokumentacji, aby mogli dzielić się swoim kodem z innymi i aby mogli lepiej zrozumieć swój kod.

starsi Programiści

poświęcając czas na dokumentowanie teraz, starsi Programiści spędzają mniej czasu na wyjaśnianiu swojego kodu innym w przyszłości.

mogą również pisać bardziej złożony kod. Dokumentacja w prostym języku pozwala innym używać jej jak Czarnej Skrzynki, bez konieczności rozumienia wewnętrznego działania.

zespoły & projekty open source

zmiany personalne mogą przynieść ogromne spowolnienie projektu. Aktualny i dobrze udokumentowany kod może służyć jako zabezpieczenie przed takimi spowolnieniami i pozwolić pozostałym członkom zespołu zrobić krok wstecz, przejrzeć kod z wysokiego poziomu i zdecydować o najlepszym kierunku działania, a w razie potrzeby na pokładzie nowych pracowników.

Ty

dokumentując kod, musisz go podsumować. Aby właściwie podsumować, musisz być w stanie to zrozumieć, trzymając różne części w głowie w tym samym czasie. Pisanie lub współtworzenie dokumentacji jest skrótem do prawdziwego zrozumienia bazy kodu, wnoszenia ogromnego wkładu i poczucia się wielką częścią wspaniałego zespołu.

dobra dokumentacja może wyschnąć nasze doświadczenie w kodowaniu

jako programista prawdopodobnie słyszałeś o zasadzie nie powtarzaj się jako kluczu do pisania czystego i zwięzłego kodu. Zamiast powtarzać ten sam blok kodu kilka razy, napisz funkcję, która może być napisana raz i zastosowana w całej aplikacji.

w ten sam sposób ty i twój zespół nie powinniście napotkać podobnych problemów, a następnie wymyślać koła za każdym razem, gdy spróbujecie je rozwiązać. Na przykład, Czy kiedykolwiek słyszałeś jednego ze swoich współpracowników lub znalazłeś się mówiąc:

” Agh, rozwiązałem coś bardzo podobnego do tego, ale nigdy nie pamiętam, jak to robię, gdy pojawia się… Powinienem to gdzieś zapisać, co?”

następnie ponownie skanujesz te same wątki przepełnienia stosu.

oszczędź sobie i swoim współpracownikom tego smutku, postępując zgodnie z duchem suchej zasady i pisząc dokument, który możesz wykorzystać za każdym razem, gdy pojawi się problem! Pomoże to Tobie i innym członkom Twojego zespołu zaoszczędzić czas i być bardziej skutecznym w pisaniu prostszego, łatwiejszego w zarządzaniu i wydajniejszego kodu.

jak wpłynęła na Ciebie dokumentacja kodu lub jej brak?