Există o mulțime de acronime atunci când vine vorba de dezvoltarea de software. SĂRUT, SEC, SOLID … și așa mai departe și așa mai departe. Dar, când vine vorba de documentarea sau comentarea codului dvs., nu există o simplă slogană.

De ce este asta?

Documentarea ar trebui să fie la fel de importantă pentru un dezvoltator ca toate celelalte fațete ale dezvoltării

În acest articol, voi argumenta de ce documentarea codului dvs. va duce la a deveni un dezvoltator mai bun și va contribui la a fi un membru excelent al echipei.

Nu are nimeni timp pentru asta

Principalul motiv pentru care codul rămâne nedocumentat este din cauza timpului.

Atunci când dezvoltăm o caracteristică care trebuie finalizată într-un anumit interval de timp, rareori avem un moment pentru a opri totul și a ne concentra asupra documentării codului nostru.

În afară de proiectarea și scrierea codului în sine, trebuie să fim supuși revizuirilor codului, testelor de automatizare și adăugării testelor unitare (pentru a numi câteva lucruri). Documentația este aproape lăsată în afara ecuației.

Este cel mai puțin gândit detaliu care poate face cea mai mare diferență în viitor.

Indiferent de ceea ce dezvolți, este posibil ca într-o zi tu sau unul dintre colegii tăi să trebuiască să îl revizitezi. Când va veni acea zi, nu vă veți aminti atât de clar ce ați scris și de ce.

Și dacă vă amintiți, pot exista unele cazuri de margine sau utilizări specifice care ar putea să nu fie clar evidente. Soluția evidentă este documentație.

Folosind acel timp suplimentar pentru a scrie o descriere corectă a ceea ce ați lucrat, veți economisi imens cantități de timp în viitor.

Data viitoare când cineva vrea să înțeleagă ce se întâmplă în interiorul codului dvs., tot ce trebuie să faceți este să indicați documentația. Vă va economisi timp, deoarece nu veți avea nevoie să explicați lucrurile și vă va economisi timp, deoarece nu vor depinde de voi.

Și la urma urmei, când tu, ca dezvoltator, trebuie să înțelegi ceva despre un anumit aspect al codării, ce faci?

? Mergi la documentație?

Codul bun nu are nevoie de documentație

Da, știu, știu … codul bine scris, care este concis și bine gândit, nu trebuie documentat. Se citește ca o poveste.

Deși poate fi așa, nu renunță la necesitatea documentării și iată de ce:

  1. Suntem prea familiarizați cu robustețea codului care cuprinde o caracteristică. Privind la o secțiune de cod, este posibil să nu fie clar că există alte secțiuni care sunt profund legate de aceasta.
  2. Fiecare serviciu pe care îl creați are un API unic. Scrierea modului de utilizare a acelui API necesită documentație care poate fi citită în afara codului. Nu doriți să umflați clasa în sine cu detalii despre modul de utilizare a API-ului.
  3. Colegii care lucrează în diferite departamente (care nu pot fi dezvoltatori) ar putea dori să înțeleagă ce ați făcut și cum funcționează.
  4. Doar actul în sine vă poate determina să priviți diferit codul pe care l-ați scris. Explicarea a ceea ce face codul dvs. vă va determina să evaluați validitatea acestuia și să luați în considerare schimbarea lucrurilor dacă acestea nu vă îndeplinesc așteptările.
  5. De dragul posterității
De ce conteaza documentarea si de ce ar trebui sa
„O persoană care scrie cu un creion într-un caiet cu așchii de creion pe el” de Catalogul gândirii pe Unsplash

Cum se scrie o documentație bună

O documentare bună este ca un bloc bun de cod. Scurt, simplu și ușor de înțeles. Iată câteva linii directoare pe care le puteți urma:

  • Înțelegeți către cine se adresează documentația. Este doar pentru dezvoltatori? Există un public mai larg? Înțelegerea acestui lucru vă va economisi timp, deoarece veți ști dinainte cât de elaborat în explicații.
  • Scrieți un fundal scurt, dar descriptiv, explicând principalele puncte ale ceea ce ați construit. Acest lucru îi va ajuta pe cititori să înțeleagă scopul caracteristicii și să verifice relevanța acesteia pentru ceea ce vor să știe.
  • Enumerați și descrieți principalele perspective ale caracteristicii dvs., asigurându-vă că indicați orice dependență care există cu alte caracteristici.
  • Asigurați-vă că există un timestamp, pentru a le spune cititorilor validitatea documentației. De asemenea, dacă utilizați anumite biblioteci, asigurați-vă că includeți și versiunile lor.
  • Fii generos cu exemplele de codare, detaliind cum să folosești corect funcția pe care ai scris-o și să prezinți rezultatele așteptate.

Exemple

Pentru a înțelege mai bine cum arată documentația bună, vom examina câteva exemple extraordinare: Rețeaua de dezvoltatori Mozilla (MDN), Django și Dunga.

1611934446 584 De ce conteaza documentarea si de ce ar trebui sa
Observați linkurile rapide din partea de sus pentru o navigare mai ușoară

În documentația MDN, puteți vedea clar că fiecare pagină începe cu o scurtă explicație despre subiect.

Apoi, se procedează la detalierea cazurilor de utilizare și a metodelor. În cele din urmă, arată ce browsere sunt compatibile cu funcția și oferă linkuri către materialele relevante.

1611934446 511 De ce conteaza documentarea si de ce ar trebui sa
În documentația Stripe, fiecare subiect are fragmente de cod care pot fi vizualizate în diferite limbi de codare
1611934446 926 De ce conteaza documentarea si de ce ar trebui sa

Documentația Django este foarte robustă. Indiferent de nivelul de codare, acestea vă încep cu o prezentare generală și tutoriale.

Apoi, parcurg fiecare subiect, detaliază-l meticulos, oferind fragmente de cod scurte și concise care demonstrează ce trebuie făcut.

Sper că am reușit să subliniez importanța documentării și v-am oferit câteva indicații despre cum să începeți să vă documentați codul. Dacă aveți o idee pentru un acronim pentru documentare, nu ezitați să faceți acest lucru în comentariile de mai jos.

Poate KID – Keep Eut Ddocumentat?

Dacă ți-a plăcut acest articol, bate din palme pentru ca și alții să se poată bucura de el! ???