code Documentation: The Complete Beginner’ s Guide
sunteți un pic moduri în primul loc de muncă de programare, și lucrurile devin mai ușor. La început, tot codul cu care ai avut de-a face ar fi putut să te copleșească și să te confunde, dar începi să te obișnuiești. E grozav! Acum vă întrebați cum să luați codul pe care îl scrieți la nivelul următor. Deși există o mulțime de lucruri de învățat despre stiva dvs. de programare, dintre care multe vă vor face un programator mai bun, există câteva care vă vor servi indiferent în ce stivă lucrați. Una dintre acestea este documentația codului.
mulți dezvoltatori nu scriu suficientă documentație, fie pentru că nu văd valoarea, fie pentru că simt că nu au timp. Nu trebuie să fii unul dintre acei dezvoltatori. Cu puțin timp și multă practică, puteți adăuga documentație pentru codul dvs., ceea ce face ca citirea acestuia să fie o bucurie de utilizat atât pentru dvs., cât și pentru oricine altcineva care vine.
documentația bună vine în multe forme
când majoritatea dezvoltatorilor se gândesc la documentația codului, se gândesc la comentarii. Comentariile pot fi adăugiri valoroase la cod, dar nu sunt singura definiție a documentației. Documentația este orice scrieți în plus față de codul dvs. pentru a ajuta pe altcineva să înțeleagă cum funcționează. S-ar putea să nu vă gândiți la asta în acest fel, dar un bun exemplu de documentare a codului este un fișier README. Un bun exemplu de documentație de bază este Expresul.js fișier README. Acesta răspunde la câteva întrebări importante despre cadru și vă spune cum îl puteți include în proiectul dvs., cum să îl instalați și cum să rulați teste.
documentația bună poate veni și sub formă de documentație API. Încă o dată, expres.js oferă un exemplu foarte bun. Această versiune a documentației este mai mult o bibliotecă de referință pentru dezvoltatorii care utilizează cadrul. Veți găsi răspunsuri la întrebări despre ce fac funcțiile individuale și ce înseamnă diferiți parametri pentru aceste funcții. Fără această documentație de calitate, Express nu ar avea aproape la fel de multe Echipe folosind-o ca și ei.
și, desigur, puteți utiliza comentarii în linie pentru a documenta codul prea. Aceste tipuri de comentarii, de obicei, nu sunt folosite pentru a învăța oameni din afara propriei Echipe despre Cod. În schimb, sunt utile pentru a explica ce se întâmplă într-un anumit cod colegilor de echipă sau viitorului tău.
de ce ar trebui să vă documentați Codul
după cum sa menționat mai sus, mulți dezvoltatori nu înțeleg scopul documentării codului. Ei vor argumenta că un cod bun ar trebui să se auto-documenteze și că nu ar trebui să-l explici. Acești oameni sunt, într-un cuvânt, greșit. Adevărul este că documentația bună este o parte esențială a oricărei baze de cod. De ce? Pentru că oamenii nu ar trebui să citească tot codul pentru a înțelege ce face. “Oamenii” din acea propoziție anterioară se pot referi la oricine, inclusiv la sinele tău viitor.
adevărul este că adesea,” oamenii ” care vor avea nevoie să înțeleagă codul după ce este scris sunteți voi. Acea mică logică care părea atât de inteligentă când ai scris-o acum șase luni ar putea fi dificil de înțeles astăzi. Dacă codul dvs. este bine documentat, nu trebuie să vă petreceți timp încercând să înțelegeți ce face. Veți putea petrece câteva secunde uitându-vă la descriere și apoi reveniți la ceea ce lucrați chiar acum.
dacă aveți norocul să lucrați la un cod folosit de zeci sau sute de dezvoltatori, documentația bună este și mai importantă. Viața utilizatorilor dvs. va fi îmbunătățită semnificativ de timpul petrecut scriind o documentație bună și vă vor mulțumi pentru asta. Literalmente!
cheia de reținut este că o documentație bună economisește mai mult timp decât este nevoie pentru a o scrie. Ar putea fi timpul tău, sau ar putea fi timpul membrilor echipei sau chiar al oamenilor pe care nu îi vei întâlni niciodată. Uneori, scrierea documentației vă va ajuta chiar să recunoașteți o parte a codului dvs. care este prea complicată, astfel încât să o puteți simplifica.
unele greșeli comune de documentare
ca dezvoltator junior, va trebui să petreceți timp învățând ce face documentația eficientă. Vestea bună este că poți învăța de la oameni care au plecat înaintea ta, astfel încât să poți evita greșelile obișnuite.
under-Documentation
o greșeală comună văd cu documentația de cod este de a documenta informații care este deja clar vizibil. De exemplu, dezvoltatorii leneși vor adăuga “documentație” la o funcție adăugând un bloc care oferă numele unei funcții, precum și numele fiecărui parametru și tipurile lor individuale. Acest tip de documentație este inutil! Este nevoie de câteva secunde pentru ca cineva să citească numele funcției și parametrii necesari. Asta nu e documentație, e doar repetiție. În schimb, documentația ar trebui să includă un pic rapid de informații despre ceea ce face funcția și modul în care fiecare parametru modifică comportamentul funcției sau de ce este necesar.
Supra-documentare
modelul opus poate fi, de asemenea, o problemă serioasă. Pentru a evita scrierea prea puțină documentație, unii dezvoltatori le place să scrie explicația pentru fiecare pic de logică care este conținută într-o funcție. Ei documentează meticulos fiecare rațiune care a intrat în crearea funcției. Până când au terminat, s-ar putea să fi petrecut atâta timp scriind funcția așa cum au făcut-o scriind documentația. Ce e mai rău, documentația este adesea dificil de înțeles și durează la fel de mult ca citirea codului. Acest tip de documentație este, de asemenea, o pierdere de timp. În schimb, documentația bună oferă o explicație de bază atât pentru ce, cât și pentru ce. Dacă există părți deosebit de dificile ale codului de înțeles, atunci documentația ar trebui să explice doar acele părți.
bazându-vă pe teste pentru a documenta
ocazional, veți întâlni pe cineva care susține că cea mai bună formă de documentare sunt testele unitare. Această abordare are un neajuns major: citirea testelor unitare este adesea la fel de dificil de făcut ca citirea codului în sine. Orice dezvoltator care dorește să afle ce face codul dvs. va avea un prim pas important în timp ce vânează și citește toate testele dvs. unitare. Mulți vor renunța doar înainte de a realiza ceea ce și-au propus să facă. În timp ce testarea unității este un plus valoros pentru orice bază de cod, nu este un înlocuitor pentru o documentație bună.
modalități de a duce documentația la nivelul următor
dacă lucrați pe o bază de cod mare, documentația codului se poate simți descurajantă, mai ales dacă nu ați fost sârguincios în ceea ce privește documentarea codului până în acest moment. S-ar putea simți ca și cum ai încerca să fierbi Oceanul. Dacă aveți o bază de cod mare sau una în care știți că documentația bună este critică, vă recomandăm să investigați instrumentele automate de documentare a codului. Aceste instrumente simplifică drastic procesul de scriere a documentației consistente și bune pentru o întreagă echipă. Un instrument precum GhostDoc va privi inteligent codul dvs. și va folosi șabloanele stabilite de echipa dvs. pentru a începe documentația cu câteva apăsări de taste. Instrumentele automate de documentare elimină unul dintre celelalte motive comune pentru a se opune scrierii documentației: durează prea mult timp.
odată ce aveți documentație consistentă, alte instrumente vă permit să partajați această documentație cu ușurință. Instrumentele automate de documentare elimină durerea din dezvoltarea unei documentații bune pentru lucruri precum API-urile publice pe care le oferă codul dvs.
începeți astăzi
scrierea unei documentații excelente este mult mai ușoară decât scrierea codului. Spre deosebire de cod, documentația nu este o întreprindere totul sau nimic. Începeți cu un obiectiv de a scrie documentație bună pentru o funcție în fiecare zi. Acest tip de practică construiește obiceiuri sănătoase și veți vedea răsplata pe drum atunci când petreceți mult mai puțin timp încercând să înțelegeți părți din baza dvs. de cod. În timp, va începe să se simtă greșit atunci când scrieți cod care nu are documentație bună. Veți începe să indicați modalități de îmbunătățire a documentației colegilor dvs. în timpul revizuirii codului. Un mic obicei va îmbunătăți codul echipei dvs. pentru întreaga dvs. afacere.
Aflați cum GhostDoc poate ajuta pentru a simplifica comentariile XML, produce și menține documentația de ajutor de calitate.
despre autor
Eric Boersma
Eric Boersma este un dezvoltator de software și manager de dezvoltare care a făcut totul, de la securitatea IT în domeniul farmaceutic până la scrierea de software de informații pentru Guvernul SUA până la construirea de echipe internaționale de dezvoltare pentru organizații non-profit. Îi place să vorbească despre lucrurile pe care le-a învățat pe parcurs și îi place să asculte și să învețe și de la ceilalți.
