Koodin dokumentointi on prosessi, jossa ohjelmoija dokumentoi koodin. Se on tunnettu termi insinöörien keskuudessa. Jos he eivät tee tätä, se johtaa koodin huonoon luettavuuteen ja vaikeaan ylläpitoon muille tiimin jäsenille.
Koodin dokumentointi eroaa projektidokumentoinnista, sillä se tähtää lähinnä siihen, miten järjestelmä toimii, mutta näillä kahdella prosessilla on jotain yhteistä – vaatimukset ammattimaisen työkalun käytöstä. Tässä artikkelissa luon katsauksen joihinkin suosittuihin työkaluihin koodidokumentaation luomiseksi.
LaTex
LaTeX on asiakirjojen laadukkaan vedostuksen valmistelujärjestelmä. Sitä käytetään useimmiten keskisuuriin ja suuriin teknisiin tai tieteellisiin asiakirjoihin, mutta sitä voidaan käyttää lähes mihin tahansa julkaisemiseen.
LaTeX ei ole tekstinkäsittelyohjelma! Sen sijaan LaTeX kannustaa kirjoittajia olemaan huolehtimatta liikaa asiakirjojensa ulkonäöstä vaan keskittymään oikean sisällön tuottamiseen.
LaTeX on laadukas kirjasinkirjoitusjärjestelmä; se sisältää teknisten ja tieteellisten asiakirjojen tuottamiseen suunniteltuja ominaisuuksia. LaTeX on de facto standardi tieteellisten asiakirjojen viestinnässä ja julkaisemisessa. LaTeX on saatavilla vapaana ohjelmistona.
LaTeXin käytöstä ei tarvitse maksaa, ts, ei ole lisenssimaksuja tms.
Pandoc
Pandoc ymmärtää useita hyödyllisiä markdown-syntaksin laajennuksia, kuten asiakirjan metatiedot (otsikko, kirjoittaja, päivämäärä); alaviitteet; taulukot; määritelmäluettelot; yli- ja aliviivaukset; yliviivaus; tehostetut järjestetyt luettelot (aloitusnumerolla ja numerointityylillä on merkitystä); juoksevia esimerkkiluetteloita; rajattuja koodilohkoja, joissa on syntaksien korostus; älykkäitä lainausviivoja, väliviivoja ja ellipsejä; markdownia HTML-lyhykkeiden sisällä; ja inline-LaTeXiä. Jos halutaan tiukka markdown-yhteensopivuus, kaikki nämä laajennukset voi kytkeä pois päältä.
Pandocia voi muokata monin tavoin tarpeisiinsa sopivaksi, mukaan lukien mallijärjestelmä ja tehokas järjestelmä suodattimien kirjoittamiseen.
Pandoc sisältää Haskell-kirjaston ja itsenäisen komentoriviohjelman. Markdownin avulla voit kirjoittaa käyttäen helppolukuista ja helposti kirjoitettavaa tavallista tekstimuotoa ja muuntaa sen sitten rakenteellisesti kelvolliseksi XHTML:ksi (tai HTML:ksi).
Markdownin muotoilusyntaksin ensisijainen suunnittelutavoite on tehdä siitä mahdollisimman luettava. Ajatuksena on, että Markdown-muotoiltu dokumentti olisi voitava julkaista sellaisenaan, tavallisena tekstinä, ilman että se näyttää siltä, että sitä olisi merkitty tunnisteilla tai muotoiluohjeilla. Vaikka Markdownin syntaksiin ovat vaikuttaneet useat olemassa olevat tekstistä HTML:ksi -suodattimet, suurin yksittäinen inspiraation lähde Markdownin syntaksille on tavallisen tekstisähköpostin muoto.
LiveEdu
LiveEdun avulla voit lähettää koodidokumentaatiosi ja luoda ”videokoodidokumentaatiota”.
Education Ecosystem on hajautettu oppimisen ekosysteemi, joka opettaa ammattilaisia ja korkeakouluopiskelijoita rakentamaan oikeita tuotteita. Tuotettamme voi kuvata Pluralsightin ja Twitchin hybridiksi. Rakennamme maailman suurinta oppimisen ekosysteemiä tulevaisuuden teknologia-aiheille, kuten tekoälylle, kyberturvallisuudelle, pelikehitykselle, datatieteelle, kryptovaluutoille ja ohjelmoinnille. Education Ecosystem on videopohjainen, ja jokainen projekti sisältää videoita, jäsennellyn projektin hahmotelman, projektin repon ja ladattavia resursseja. Käyttäjät voivat kloonata projektiresursseja Education Ecosystem Gitistä ja ajaa sovelluksia paikallisella koneellaan.
Sphinx
Sphinx on Georg Brandlin kirjoittama ja BSD-lisenssillä lisensoitu työkalu, jolla on helppo luoda älykästä ja kaunista dokumentaatiota.
Sphinx on alunperin luotu Python-dokumentaatiota varten, ja siinä on erinomaiset välineet ohjelmistoprojektien dokumentaatiolle useilla eri kielillä. Tässä muutamia ominaisuuksia:
- Tulostusmuodot: HTML (mukaan lukien Windows HTML Help), LaTeX (tulostettavia PDF-versioita varten), ePub, Texinfo, käsikirjasivut, tavallinen teksti.
- Laajat ristiviittaukset: semanttinen merkintä ja automaattiset linkit funktioita, luokkia, sitaatteja, sanaston termejä ja muita vastaavia tietoja varten.
- Hierarkkinen rakenne: dokumenttipuu on helppo määritellä, ja siinä on automaattiset linkit sisaruksiin, vanhemmiin ja lapsiin.