valoarea documentației de cod

documentația de cod este colecția de imagini ușor de înțeles și descrieri scrise care explică ce face o bază de cod și cum poate fi utilizată.

acesta poate fi comentarii explicative simple de mai sus funcții și blocuri, sau un manual Dezvoltator cu drepturi depline, complet cu stil prescriptiv dos-and-don ‘ ts, prezentări generale ale fiecărei părți a cererii, și abordări la cele mai comune tipuri de sarcini de codificare.

este adesea cel mai bine să găsiți un mediu fericit între aceste două extreme atunci când luați decizia conștientă de a comenta codul dvs. și de a schița zonele gnarlier ale unei baze de cod într-un limbaj simplu.

de ce să vă documentați codul?

de ce să te deranjezi scriind despre codul tău, în loc să scrii doar Cod? Nu ar fi mai productiv oricum?

Mental Save Points

documentația este ca un punct de salvare mentală pentru acele momente când în cele din urmă obțineți ceea ce se întâmplă la sfârșitul zilei și nu doriți să pierdeți impulsul. Codul bine documentat vă va asigura că atunci când trebuie să vă scufundați înapoi mâine dimineață (sau peste câteva luni), nu va trebui să vă luați cât mai mult timp pentru a vă ridica la viteză.

Codul documentat este reutilizat

diferența dintre o bibliotecă folosită și o bibliotecă neutilizată se reduce adesea la documentația sa.

cine dorește să utilizeze o bibliotecă open-source fără documente sau să contribuie la un proiect fără documente? Aproape nimeni.

în majoritatea cazurilor, preferați să utilizați o bibliotecă mai puțin puternică care are documente. De ce? Deoarece documentația transmite alte puncte de informații despre o bază de cod. Dezvoltatorii cred că proiectul merită timpul și energia pentru a scrie despre el într-un limbaj simplu, astfel încât oricine ar putea fi interesat să poată începe rapid și să învețe cum funcționează și de ce au fost luate decizii cheie.

găsirea unui proiect nou, interesant și bine documentat în limba preferată poate fi foarte interesantă și distractivă. Să ne uităm la alternativa extremă: fiind necesar să se utilizeze o bibliotecă de cod fără documente și să contribuie potențial la o bază de cod aparent bizantină… sună destul de dureros, nu?

deci, de ce nu v-ați documentat propriul cod?

documentarea codului face parte din scrierea codului bun

o piatră de temelie a codului bun este mentenabilitatea, realizată prin documentație inteligibilă și lizibilă.

există mai multe modalități de documentare a codului:

• alegerea unor nume bune pentru variabile și funcții
• lăsând scurte comentarii în cod pentru a ajuta la oferirea contextului viitorilor cititori
• adăugarea de imagini ilustrative, cum ar fi diagrame de relații de secvență și entitate
• furnizarea de documente API, descriind fiecare clasă, metodă, argument și valoare returnată
• folosind un limbaj tipuri ca documentație)

compara două exemple

să presupunem că sunteți obtinerea unor date de la un API backend și” ingressing ” – l-transformarea într – o formă mai util pentru un interfață frontală. Iată prima dintre cele două soluții posibile.

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

codul de mai sus are potențialul de a fi dureros. Puteți vedea după nume că acesta este un fel de convertor care ia w ca param.

se pare că returnează un antet, poate detalii și ceva numit turații. De unde au venit turațiile? Desigur, nu există detalii despre numele variabilelor primite note, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS… sau există? Este rr prescurtarea de la returned rev? Cine poate spune.

să ne uităm la al doilea exemplu.

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

Wow, cât de diferit! Această funcție se află într-un fișier util, astfel încât fișierul principal este deja mai puțin aglomerat. Este, de asemenea, scris în TypeScript în loc de JavaScript simplu, așa că avem avantajul definițiilor de tip pentru a ne ajuta să ne ghidăm.

convertim widgetRespDTOs în widget s. deși scurtat, avem cunoștințe depline despre ceea ce este wResp. Creăm un widgetHeader și un widgetDetail, care este ușor de văzut. De asemenea, înțelegem ce sunt oTS și cTS. Putem spune WidgetRevisionsRespDTO s sunt imbricate în interiorul WidgetRespDTO.

cineva a redenumit foarte amabil variabilele primite, astfel încât toți cei care văd acest cod să știe ce sunt. În cele din urmă, vedem că un Widget trebuie să fie compus din obiectul returnat {widgetHeader, widgetDetail, widgetRevisions}, deoarece trebuie să se potrivească cu tipul de retur Widget specificat în partea de sus.

ce Cod te-ai simți mai bine să folosești?

cine beneficiază?

codul bine documentat beneficiază mulți oameni:

Dezvoltatori juniori

deoarece este într-un limbaj simplu și ușor de înțeles, documentația ajută dezvoltatorii juniori și noii membri ai echipei să se simtă încrezători sărind într-o bază de cod. Acest lucru previne frustrarea și abandonarea timpurie a unei sarcini, deoarece devine prea complicată prea repede.

de asemenea, este util ca dezvoltatorii juniori să-și scrie propria documentație, astfel încât să poată partaja codul lor cu alții și astfel să poată înțelege mai bine codul lor.

Senior developers

prin luarea de timp pentru a documenta acum, devs senior petrec mai puțin timp explicând codul lor altora în viitor.

de asemenea, pot scrie cod mai complex. Documentația limbajului simplu permite altora să o folosească ca o cutie neagră, fără a fi nevoie să înțeleagă funcționarea interioară.

Echipe & proiecte open source

schimbările de personal pot aduce o încetinire extraordinară unui proiect. Codul actualizat și bine documentat poate servi drept asigurare împotriva unor astfel de încetiniri și permite membrilor echipei rămase să facă un pas înapoi, să revizuiască Codul de la un nivel înalt și să decidă asupra celui mai bun curs de acțiune înainte și, dacă este necesar, la bordul noilor angajați.

tu

când documentarea cod, trebuie să-l rezuma. Pentru a rezuma corect, trebuie să fii capabil să o înțelegi, ținând în același timp diferitele părți din cap. Scrierea sau contribuția la documentație este o scurtătură pentru a înțelege cu adevărat o bază de cod, a aduce contribuții uriașe și a te simți ca o mare parte a unei echipe grozave.

documentația bună poate usca experiența noastră de codificare

ca programator, probabil că ați auzit de principiul Don ‘ t Repeat Yourself ca o cheie pentru scrierea unui cod curat și concis. În loc să repetați același bloc de cod de mai multe ori, scrieți o funcție care poate fi scrisă o singură dată și utilizată în toată aplicația.

în același mod, Tu și echipa ta nu ar trebui să vă confruntați cu probleme similare și apoi să reinventați roata de fiecare dată când încercați să le rezolvați. De exemplu, ai auzit vreodată unul dintre colegii tăi sau te-ai trezit spunând:

„Agh, am rezolvat ceva foarte asemănător cu acesta, dar nu-mi amintesc niciodată cum o fac când apare… Ar trebui să scriu undeva, nu?”

apoi vă aflați scanând aceleași fire de depășire a stivei din nou și din nou.

Salvează-te pe tine și pe colegii tăi această durere urmând spiritul principiului uscat și scriind un document pe care îl poți folosi de fiecare dată când apare problema! Acest lucru vă va ajuta pe dvs. și pe ceilalți din echipa dvs. să economisiți timp și să fiți mai eficienți în scrierea unui cod mai simplu, mai ușor de gestionat și mai eficient.

cum te-a afectat documentația codului sau lipsa acesteia?