Code Documentation: the Complete Beginner’ s Guide
you ‘ re a little ways into your first programming job, and things are getting governing. Aluksi, kaikki koodi piti käsitellä ehkä häkellyttää ja hämmentää sinua, mutta olet alkanut ymmärtää sitä. Hienoa! Nyt mietit, miten Viet kirjoittamasi koodin seuraavalle tasolle. Vaikka on olemassa paljon asioita oppia ohjelmointi pino, joista monet tekevät sinusta paremman ohjelmoija, on olemassa muutamia, jotka palvelevat sinua riippumatta siitä, mitä pino työskentelet. Yksi niistä on koodidokumentaatio.
monet kehittäjät eivät kirjoita tarpeeksi dokumentaatiota joko siksi, että he eivät näe arvoa tai koska he kokevat, ettei heillä ole aikaa. Sinun ei tarvitse olla yksi niistä kehittäjistä. Kun sinulla on hieman aikaa ja paljon harjoittelua, voit lisätä koodiisi dokumentaatiota, joka tekee sen lukemisesta ilon käyttää sekä sinulle että kaikille muille, jotka tulevat mukaan.
hyvä dokumentaatio tulee monessa muodossa
kun suurin osa kehittäjistä ajattelee koodidokumentaatiota, he ajattelevat kommentteja. Kommentit voivat olla arvokkaita lisäyksiä koodiin, mutta ne eivät ole ainoa dokumentaation määritelmä. Dokumentaatio on mitä tahansa, mitä kirjoitat koodin lisäksi auttaaksesi jotakuta muuta ymmärtämään, miten se toimii. Et ehkä ajattele sitä näin, mutta hyvä esimerkki koodidokumentaatiosta on README-tiedosto. Hyvä esimerkki perusdokumentaatiosta On Express.js README-tiedosto. Se vastaa useisiin kehystä koskeviin tärkeisiin kysymyksiin ja kertoo, miten voit sisällyttää sen projektiisi, miten se asennetaan ja miten testit suoritetaan.
hyvä dokumentaatio voi tulla myös API-dokumentaation muodossa. Vielä kerran, Express.js antaa hyvän esimerkin. Tämä dokumentaatioversio on enemmän viitekehystä käyttävien kehittäjien referenssikirjasto. Löydät vastauksia kysymyksiin siitä, mitä yksittäiset funktiot tekevät ja mitä näiden funktioiden eri parametrit tarkoittavat. Ilman laadukasta dokumentaatiota Expressillä ei olisi läheskään yhtä monta tiimiä, jotka käyttävät sitä.
ja toki myös rivikommenteilla voi dokumentoida koodia. Tuollaisilla kommenteilla ei yleensä opeteta oman joukkueen ulkopuolisille koodista. Sen sijaan, ne ovat hyödyllisiä selittää, mitä tapahtuu tietyn vähän koodia joukkuetovereille tai tulevaisuuden itse.
miksi koodisi pitäisi dokumentoida
kuten edellä todettiin, monet kehittäjät eivät ymmärrä koodidokumentoinnin tarkoitusta. He väittävät, että hyvän koodin pitäisi olla itse dokumentoivaa, eikä sitä tarvitse selittää. Nämä ihmiset ovat sanalla sanoen väärässä. Totuus on, että hyvä dokumentointi on olennainen osa mitä tahansa koodipohjaa. Miksi? Ihmisten ei pitäisi lukea kaikkia koodejasi ymmärtääkseen, mitä se tekee. “Ihmiset” tuossa edellisessä lauseessa voivat viitata keneen tahansa, myös tulevaan itseen.
totuus on, että usein” ihmiset”, joiden täytyy ymmärtää koodia sen kirjoittamisen jälkeen, ovat sinä. Sitä logiikkaa, joka tuntui niin nokkelalta, kun kirjoitit sen puoli vuotta sitten, voi olla vaikea ymmärtää tänään. Jos koodi on hyvin dokumentoitu, sinun ei tarvitse viettää aikaa yrittää ymmärtää, mitä se tekee. Voit viettää muutaman sekunnin katsomalla kuvaus ja sitten palata mitä olet tekemässä juuri nyt.
jos on onni työskennellä kymmenien tai satojen kehittäjien käyttämän koodin parissa, hyvä dokumentointi on vielä tärkeämpää. Käyttäjien elämä paranee merkittävästi, kun käytät aikaa hyvän dokumentaation kirjoittamiseen, ja he kiittävät sinua siitä. Kirjaimellisesti!
tärkeää on muistaa, että hyvä dokumentointi säästää enemmän aikaa kuin sen kirjoittaminen vie. Se voi olla sinun aikaasi, tai se voi olla tiimin jäsenten aikaa, tai jopa ihmisiä, joita et koskaan tapaa. Joskus dokumentaation kirjoittaminen auttaa jopa tunnistamaan koodin liian monimutkaisen osan, joten voit yksinkertaistaa sitä.
joitakin yleisiä Dokumentointivirheitä
nuorempana kehittäjänä joutuu käyttämään aikaa oppiakseen, mikä tekee dokumentoinnista tehokasta. Hyvä uutinen on, että voit oppia ihmisiltä, jotka ovat menneet ennen sinua, jotta voit välttää yleisiä virheitä.
Alidokumentaatio
yksi yleinen virhe, jonka näen koodidokumentaatiossa, on dokumentoida jo selvästi näkyvissä olevaa tietoa. Esimerkiksi laiskat kehittäjät lisäävät funktioon “dokumentaatiota” lisäämällä lohkon, joka antaa funktion nimen sekä kunkin parametrin nimet ja niiden yksilölliset tyypit. Tällainen dokumentaatio on hyödytöntä! Kestää sekunteja, ennen kuin joku lukee funktion nimen ja sen vaatimat parametrit. Se ei ole dokumentaatiota, se on vain toistoa. Sen sijaan dokumentaation tulisi sisältää nopeasti tietoa siitä, mitä funktio tekee ja miten kukin parametri muuttaa funktion käyttäytymistä tai miksi sitä tarvitaan.
yli-dokumentaatio
päinvastainen kuvio voi olla myös vakava ongelma. Välttääkseen kirjoittamasta liian vähän dokumentaatiota, jotkut kehittäjät haluavat kirjoittaa selityksen jokaiselle pienelle logiikalle, joka sisältyy funktioon. He dokumentoivat huolellisesti kaikki perustelut, jotka menivät luomaan funktiota. He ovat ehkä kirjoittaneet funktiota yhtä kauan kuin dokumentaatiota. Mikä pahinta, dokumentaatio on usein vaikea ymmärtää ja kestää yhtä kauan kuin koodin lukeminen. Tämänkaltainen dokumentointi on myös ajanhukkaa. Sen sijaan hyvä dokumentaatio antaa perusselityksen sekä mitä että miksi. Jos koodissa on jotain erityisen Hankalia kohtia, jotka on ymmärrettävä, dokumentaation on selitettävä juuri ne osat.
vedoten testeihin dokumentoidakseen
silloin tällöin törmää johonkuhun, joka väittää, että paras dokumentointimuoto on yksikkötestit. Tässä lähestymistavassa on suuri puute: yksikkötestien lukeminen on usein aivan yhtä vaikeaa kuin itse koodin lukeminen. Jokainen kehittäjä, joka haluaa oppia, mitä koodi tekee, on iso ensimmäinen askel, kun he metsästävät ja lukea kaikki yksikkökokeet. Monet vain luovuttavat ennen kuin saavuttavat sen, mitä he lähtivät tekemään. Vaikka yksikkötestaus on arvokas lisä mihin tahansa koodipohjaan, se ei korvaa hyvää dokumentointia.
tapoja viedä dokumentaatio seuraavalle tasolle
jos työskentelet suuren koodipohjan parissa, koodidokumentointi voi tuntua pelottavalta, varsinkin jos et ole ollut ahkera dokumentoimaan koodia tähän asti. Tuntuu kuin yrittäisit keittää merta. Jos sinulla on suuri koodikanta tai sellainen, jossa tiedät hyvän dokumentaation olevan tärkeää, kannattaa tutkia automaattisia koodidokumentointityökaluja. Nämä työkalut yksinkertaistavat huomattavasti johdonmukaisen, hyvän dokumentaation kirjoittamisprosessia koko tiimille. Ghostdocin kaltainen työkalu katsoo koodiasi älykkäästi ja käyttää tiimisi luomia malleja käynnistääkseen dokumentaatiosi muutamalla näppäinpainalluksella. Automatisoidut dokumentointityökalut poistavat yhden muista yleisistä syistä vastustaa dokumentaation kirjoittamista: se vie liikaa aikaa.
kun sinulla on johdonmukainen dokumentaatio, muiden työkalujen avulla voit jakaa sen helposti. Automatisoidut dokumentointityökalut poistavat tuskan kehittämällä hyvää dokumentaatiota esimerkiksi koodisi tarjoamia julkisia API-ohjelmointirajapintoja varten.
Aloita tänään
suuren dokumentaation kirjoittaminen on paljon helpompaa kuin koodin kirjoittaminen. Toisin kuin koodi, dokumentaatio ei ole kaikki tai ei mitään-yritys. Aloita tavoitteena kirjoittaa hyvää dokumentaatiota yksi toiminto joka päivä. Tällainen käytäntö rakentaa terveellisiä tapoja, ja näet payoff tiellä, kun viettää paljon vähemmän aikaa yrittää ymmärtää osia koodin perusta. Ajan myötä se alkaa tuntua väärältä, kun kirjoittaa koodia, jolla ei ole hyvää dokumentaatiota. Alat osoittaa tapoja parantaa dokumentointia työtovereillesi koodikatselmuksen aikana. Yksi pieni tapa parantaa tiimisi koodia koko yrityksellesi.
Lue, miten GhostDoc voi auttaa yksinkertaistamaan XML-kommenttejasi, tuottamaan ja ylläpitämään laadukasta ohjedokumentaatiota.
tietoa tekijästä
Eric Boersma
Eric Boersma on ohjelmistokehittäjä ja kehityspäällikkö, joka on tehnyt kaikkea lääkealan tietoturvallisuudesta Yhdysvaltain hallituksen tiedusteluohjelmien kirjoittamiseen ja kansainvälisten kehitystiimien rakentamiseen voittoa tavoittelemattomille tahoille. Hän puhuu mielellään matkan varrella oppimistaan asioista ja nauttii myös muiden kuuntelemisesta ja oppimisesta.
