Mnoštvo je kratica kada je u pitanju razvoj softvera. POLJUBITI, SUHO, ČVRSTO ... i tako dalje i tako dalje. No, što se tiče dokumentiranja ili komentiranja vašeg koda, ne postoji jednostavna krilatica.
Zašto je to?
Dokumentacija bi programeru trebala biti jednako važna kao i sve druge aspekte razvoja
U ovom ću članku raspravljati zašto će dokumentiranje vašeg koda postati bolji programer i pridonijet će tome da budete sjajan član tima.
Nitko nema vremena za to
Glavni razlog zašto kod ostaje nedokumentiran je zbog vremena.
Kada razvijamo značajku koju treba dovršiti u određenom vremenskom okviru, rijetko imamo trenutak da sve zaustavimo i usredotočimo se na dokumentiranje našeg koda.
Osim dizajniranja i pisanja samog koda, također moramo proći i preglede koda, testove automatizacije i dodati jedinice testove (da navedemo nekoliko stvari). Dokumentacija je prilično izostavljena iz jednadžbe.
Najmanje se razmišlja o detaljima koji mogu najviše utjecati na budućnost.
Bez obzira na to što razvijate, šanse su da ćete jednog dana vi ili netko od vaših kolega to morati ponovno posjetiti. Kad taj dan dođe, nećete se tako živo sjećati što ste napisali i zašto.
A ako se sjećate, možda postoje neki rubni slučajevi ili određene primjene koje možda nisu jasno vidljive. Očito rješenje je dokumentacija .
Uzimanje dodatnog vremena za pisanje pravilnog opisa onoga na čemu ste radili uštedjet će ogromnu količinu vremena u budućnosti.
Sljedeći put kad netko želi shvatiti što se događa unutar vašeg koda, sve što morate učiniti je usmjeriti ga na dokumentaciju. Uštedjet će vam vrijeme jer nećete trebati objašnjavati stvari, a uštedjet će i vrijeme za njih jer neće ovisiti o vama.
I na kraju, kad vi kao programer morate razumjeti nešto o određenom aspektu kodiranja, što radite?
? Idete na dokumentaciju?Za dobar kod nije potrebna dokumentacija
Da, znam, znam ... dobro napisan kôd, koji je sažet i dobro promišljen, ne treba ga dokumentirati. Čita se poput priče .
Iako je to možda tako, ne odriče se potrebe za dokumentacijom, i evo zašto:
- Previše smo upoznati s robusnošću koda koji sadrži značajku. Gledajući jedan odjeljak koda, možda neće biti jasno da postoje drugi odjeljci koji su duboko povezani s njim.
- Svaka usluga koju izradite ima jedinstveni API. Za pisanje načina upotrebe tog API-ja potrebna je dokumentacija koja se može čitati izvan koda. Ne želite napumpati samu klasu detaljima o tome kako koristiti API.
- Kolege koji rade u različitim odjelima (koji možda nisu programeri) možda žele razumjeti što ste radili i kako to radi.
- Već sam čin može uzrokovati da drugačije gledate na kod koji ste napisali. Objašnjenje vašeg koda učinit će da procijenite njegovu valjanost i možda razmislite o promjeni stvari ako one ne ispunjavaju vaša očekivanja.
- Zbog potomstva
Kako napisati dobru dokumentaciju
Dobra dokumentacija je poput dobrog bloka koda. Kratko, jednostavno i lako razumljivo. Evo nekoliko smjernica koje možete slijediti:
- Shvatite kome je namijenjena dokumentacija. Je li to samo za programere? Postoji li šira publika? Ako to razumijete, uštedjet ćete vrijeme jer ćete unaprijed znati koliko treba objasniti u svojim objašnjenjima.
- Napišite kratku, ali opisnu pozadinu koja objašnjava glavne stavke onoga što ste izgradili. To će čitateljima pomoći da razumiju svrhu značajke i utvrde njezinu važnost za ono što žele znati.
- Navedite i opišite glavne perspektive vaše značajke, pazeći da istaknete sve ovisnosti koje postoje s drugim značajkama.
- Provjerite postoji li vremenska oznaka kako biste čitateljima rekli valjanost dokumentacije. Također, ako koristite određene knjižnice, svakako dodajte i njihove verzije.
- Budite velikodušni sa svojim primjerima kodiranja, detaljno opisujući kako pravilno koristiti značajku koju ste napisali i izložiti očekivane rezultate.
Primjeri
Da bismo dalje razumjeli kako izgleda dobra dokumentacija, pregledat ćemo neke izvrsne primjere: Mozillina razvojna mreža (MDN), Django i Stripe.
U MDN-ovoj dokumentaciji možete jasno vidjeti da svaka stranica započinje kratkim objašnjenjem o temi.
Zatim se nastavlja na detalje slučajeva i metoda korištenja. Konačno, pokazuje koji su preglednici kompatibilni sa značajkom i daje veze do relevantnog materijala.
Djangova dokumentacija vrlo je robusna. Bez obzira na razinu kodiranja, započinju s pregledom i uputama.
Zatim prolaze kroz svaku temu, detaljno je detaljno opisuju, dajući kratke i sažete isječke koda koji pokazuju što treba učiniti
Nadam se da sam uspio naglasiti važnost dokumentacije i dao sam vam neke upute kako započeti s dokumentiranjem koda. Ako imate ideju za kraticu za dokumentaciju, slobodno to učinite u komentarima ispod.
Možda KID - K EEP sam t D ocumented?
Ako vam se svidio ovaj članak, pljeskajte kako bi i drugi mogli uživati u njemu! ???