Koodidokumentaation arvo

Koodidokumentaatio on kokoelma helposti ymmärrettäviä kuvia ja kirjoitettuja kuvauksia, jotka selittävät, mitä koodibaasi tekee ja miten sitä voidaan käyttää.

se voi olla yksinkertaisia selittäviä kommentteja funktioiden ja lohkojen yllä, tai täysimittainen kehittäjän käsikirja, joka on täydennetty ohjaavilla tyylisillä käskyillä ja kielloilla, katsauksilla sovelluksen jokaisesta osasta ja lähestymistavoilla yleisimpiin koodaustehtäviin.

näiden kahden ääripään välillä on usein parasta löytää onnellinen välimuoto, kun tekee tietoisen päätöksen kommentoida koodiaan ja hahmotella koodebaasin gnarlier-alueet selkokielellä.

miksi dokumentoida koodi?

miksi vaivautua kirjoittamaan koodistasi pelkän koodin kirjoittamisen sijaan? Eikö se olisi tuottoisampaa?

Mental Save Points

dokumentaatio on kuin henkinen pelastuspiste niille hetkille, jolloin lopulta tajuaa, mitä tapahtuu, eikä halua menettää vauhtia. Hyvin dokumentoitu koodi varmistaa, että kun sinun täytyy sukeltaa takaisin huomisaamuna (tai useiden kuukausien kuluttua), sinun ei tarvitse ottaa niin paljon aikaa päästä vauhtiin.

dokumentoitua koodia käytetään uudelleen

käytetyn kirjaston ja käyttämättömän kirjaston ero tulee usein sen dokumentaatiosta.

Kuka haluaa käyttää paperitonta avoimen lähdekoodin kirjastoa tai osallistua paperittomaan projektiin? Melkein ei kukaan.

useimmissa tapauksissa käyttäisit mieluummin vähemmän tehokasta kirjastoa, jossa on docs. Miksi? Koska dokumentaatio välittää muita tietoja koodebaasista. Kehittäjät uskovat, että projekti on sen arvoista aikaa ja energiaa kirjoittaa siitä selkokielellä, jotta kuka tahansa, joka saattaa olla kiinnostunut, voi nopeasti aloittaa ja oppia, miten se toimii, ja miksi keskeiset päätökset tehtiin.

uuden, mielenkiintoisen ja hyvin dokumentoidun projektin löytäminen lempikielelläsi voi olla hyvin jännittävää ja hauskaa. Katsotaan äärimmäinen vaihtoehto: vaaditaan käyttämään paperiton koodikirjasto ja mahdollisesti edistää näennäisesti bysanttilainen koodibase… kuulostaa tuskalliselta.

joten miksi et ole dokumentoinut omaa koodiasi?

koodin dokumentointi on osa hyvän koodin kirjoittamista

hyvän koodin kulmakivi on ylläpidettävyys, joka saavutetaan ymmärrettävällä, luettavalla dokumentoinnilla.

koodin dokumentointiin on useita tapoja:

• hyvien nimien valitseminen muuttujille ja funktioille
• lyhyiden kommenttien jättäminen koodiin, jotta voidaan antaa asiayhteys tuleville lukijoille
• havainnollistavien kuvien, kuten sekvenssi-ja entiteettisuhdekaavioiden lisääminen
• API-dokumenttien tarjoaminen, kunkin luokan, menetelmän, argumentin ja palautusarvon kuvaaminen
• käyttäen staattisesti kirjoitettua kieltä, kuten konekirjoitusta (TypeScript) dokumentaationa)

vertaa kahta esimerkkiä

sanotaan, että saat tietoja backend API: sta ja ”ingressing” it-muuntamalla sen hyödyllisempään muotoon etupään UI. Tässä on ensimmäinen kahdesta mahdollisesta ratkaisusta.

// 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 }}

yllä oleva koodi voi olla kivulias. Nimestä näkee, että kyseessä on jonkinlainen muunnin, joka ottaa w paramikseen.

näyttää siltä, että se palauttaa otsikon, ehkä yksityiskohtia ja jotain nimeltä revs. Mistä Revit tulivat? Tarkempia tietoja tulevista muuttujan nimistä note, prsn1Id, prsn1Ln, prsn1Fn, amt, cTSei tietenkään ole… vai onko? Onko rr lyhenne sanoista returned rev? Kuka tietää.

katsotaanpa toista esimerkkiä.

// 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, }}

Vau, miten erilaista! Tämä funktio on util – tiedostossa, joten päätiedosto on jo vähemmän sotkuinen. Se on myös kirjoitettu TypeScript sijaan tavallinen JavaScript, joten meillä on hyötyä tyyppi määritelmät auttaa ohjaamaan meitä.

olemme muuttamassa widgetRespDTOs: ää widgets: ksi. vaikka se on lyhennetty, meillä on täysi tieto siitä, mitä wResp on. Luomme widgetHeader ja widgetDetail, se on helppo nähdä. Ymmärrämme myös, mitä oTS ja cTS ovat. Voimme todeta WidgetRevisionsRespDTOs: n pesivän WidgetRespDTO: n sisällä.

joku hyvin ystävällisesti nimesi saapuvat muuttujat uudelleen, joten jokainen, joka näkee tämän koodin, tietää mitä ne ovat. Lopuksi nähdään, että Widget täytyy koostua palautetusta {widgetHeader, widgetDetail, widgetRevisions} objektista, koska sen täytyy vastata yläosassa määriteltyä palautustyyppiä Widget.

mitä koodia käyttäisit paremmin?

kuka hyötyy?

hyvin dokumentoitu koodi hyödyttää monia:

Junior developers

koska se on selkokielistä ja helppotajuista, dokumentointi auttaa juniorikehittäjiä ja uusia tiimiläisiä hyppäämään varman päälle. Tämä estää turhautumista ja ennenaikaista luopumista tehtävästä, koska se muuttuu liian monimutkaiseksi liian nopeasti.

myös juniorikehittäjien on hyödyllistä kirjoittaa omat dokumentaationsa, jotta he voivat jakaa koodiaan muiden kanssa ja jotta he voivat ymmärtää koodiaan paremmin.

Senior developers

ottamalla aikaa dokumentointiin nyt, senior devs käyttää vähemmän aikaa koodinsa selittämiseen muille tulevaisuudessa.

ne voivat myös kirjoittaa monimutkaisempaa koodia. Selkokielisen dokumentaation avulla muut voivat käyttää sitä kuin mustaa laatikkoa ilman, että heidän tarvitsee ymmärtää sen sisäistä toimintaa.

tiimit & avoimen lähdekoodin projektit

henkilövaihdokset voivat tuoda projektille valtavan hidastumisen. Ajan tasalla oleva ja hyvin dokumentoitu koodi voi toimia vakuutuksena tällaisia hidastuksia vastaan ja antaa jäljelle jääneille tiimin jäsenille mahdollisuuden ottaa askel taaksepäin, tarkastella koodia korkealta tasolta ja päättää parhaasta toimintatavasta eteenpäin, ja tarvittaessa, aluksella uusia työntekijöitä.

Sinä

kun dokumentoit koodia, sinun täytyy tiivistää se. Jotta voisit tiivistää kunnolla, sinun täytyy ymmärtää se pitämällä eri osia päässäsi samaan aikaan. Kirjoittaminen tai osallistuminen dokumentaatio on oikotie todella ymmärtää codebase, tehdä valtavia panoksia, ja tunne suuri osa hienoa tiimiä.

hyvä dokumentaatio voi kuivattaa koodauskokemustamme

ohjelmoijana olet luultavasti kuullut älä toista itseäsi-periaatteesta avaimena puhtaan ja ytimekkään koodin kirjoittamiseen. Sen sijaan, että toistaisit saman koodilohkon useita kertoja, kirjoita toiminto, joka voidaan kirjoittaa kerran ja käyttää kaikkialla sovelluksessasi.

samalla tavalla sinun ja tiimisi ei pitäisi törmätä samanlaisiin ongelmiin ja keksiä pyörää uudelleen joka kerta, kun yrität ratkaista niitä. Oletko esimerkiksi koskaan kuullut jonkun työkaverisi sanovan:

” Agh, Ratkaisin jotain hyvin samankaltaista, mutta en koskaan muista, miten teen sen, kun se tulee puheeksi… Minun pitäisi varmaan kirjoittaa se jonnekin.”

huomaat sitten skannaavasi samoja pinon Ylivuotokierteitä uudelleen ja uudelleen.

pelasta itsesi ja työkaverisi tästä surusta noudattamalla KUIVAPERIAATTEEN henkeä ja kirjoittamalla dokumentti, jota voit käyttää joka kerta, kun asia tulee puheeksi! Tämä auttaa sinua ja muita tiimisi säästää aikaa, ja on tehokkaampi kirjallisesti yksinkertaisempaa, helpommin hallittavissa, ja tehokkaampaa koodia.

miten koodidokumentaatio tai sen puute on vaikuttanut sinuun?