Kodedokumentation er en proces, hvormed en programmør dokumenterer kode. Det er et velkendt begreb blandt ingeniører. Hvis de ikke gør det, fører det til dårlig læsbarhed af kode og vanskelig vedligeholdelse for andre teammedlemmer.
Kodedokumentation er forskellig fra projektdokumentation, da den primært sigter på, hvordan systemet fungerer, men disse to processer har noget til fælles – krav om at bruge et professionelt værktøj. I denne artikel giver jeg en oversigt over nogle populære værktøjer til at lave kodedokumentation.
LaTex
LaTeX er et dokumentforberedelsessystem til satsning af høj kvalitet. Det bruges oftest til mellemstore til store tekniske eller videnskabelige dokumenter, men det kan bruges til næsten alle former for udgivelse.
LaTeX er ikke et tekstbehandlingsprogram! I stedet opfordrer LaTeX forfatterne til ikke at bekymre sig for meget om udseendet af deres dokumenter, men til at koncentrere sig om at få det rigtige indhold.
LaTeX er et sættelsessystem af høj kvalitet; det indeholder funktioner, der er designet til produktion af teknisk og videnskabelig dokumentation. LaTeX er de facto-standard for kommunikation og offentliggørelse af videnskabelige dokumenter. LaTeX er tilgængelig som gratis software.
Du skal ikke betale for at bruge LaTeX, dvs, der er ingen licensgebyrer osv.
Pandoc
Pandoc forstår en række nyttige markdown-syntaksudvidelser, herunder dokumentmetadata (titel, forfatter, dato); fodnoter; tabeller; definitionslister; superscript og subscript; overstregning; forbedrede ordnede lister (startnummer og nummereringsstil har betydning); lister med løbende eksempler; afgrænsede kodeblokke med syntaksfremhævning; smarte anførselstegn, streger og ellipser; markdown inden for HTML-blokke; og inline LaTeX. Hvis der ønskes streng markdown-kompatibilitet, kan alle disse udvidelser slås fra.
Der er mange måder at tilpasse Pandoc på, så det passer til dine behov, herunder et skabelonsystem og et kraftfuldt system til at skrive filtre.
Pandoc indeholder et Haskell-bibliotek og et selvstændigt kommandolinjeprogram. Biblioteket indeholder separate moduler for hvert input- og outputformat, så tilføjelse af et nyt input- eller outputformat kræver blot tilføjelse af et nyt modul.
Pandoc er gratis software, udgivet under GPL.
Markdown
Markdown er et tekst-til-HTML-konverteringsværktøj for webskribenter. Markdown giver dig mulighed for at skrive ved hjælp af et letlæseligt og letskrevet almindelig tekstformat og derefter konvertere det til strukturelt gyldig XHTML (eller HTML).
Det overordnede designmål for Markdowns formateringssyntaks er at gøre den så læsbar som muligt. Ideen er, at et Markdown-formateret dokument skal kunne offentliggøres som det er, som almindelig tekst, uden at det ser ud som om det er blevet markeret med tags eller formateringsinstruktioner. Markdowns syntaks er blevet påvirket af flere eksisterende tekst-til-HTML-filtre, men den største inspirationskilde til Markdowns syntaks er formatet for almindelig tekst-e-mail.
LiveEdu
LiveEdu giver dig mulighed for at udsende din kodedokumentation og skabe “Videokodedokumentation.”
Education Ecosystem er et decentraliseret læringsøkosystem, der lærer fagfolk og universitetsstuderende at bygge rigtige produkter. Du kan beskrive vores produkt som en hybrid af Pluralsight og Twitch. Vi er ved at opbygge verdens største læringsøkosystem for fremtidige teknologiske emner såsom kunstig intelligens, cybersikkerhed, spiludvikling, datalogi, kryptovalutaer og programmering. Education Ecosystem er videobaseret, og hvert projekt indeholder videoer, en struktureret projektoversigt, projektrepo og ressourcer, der kan downloades. Brugerne kan klone projektressourcerne fra Education Ecosystem Git og køre programmerne på deres lokale maskine.
Sphinx
Sphinx er et værktøj, der gør det nemt at lave intelligent og smuk dokumentation, skrevet af Georg Brandl og licenseret under BSD-licensen.
Det blev oprindeligt skabt til Python-dokumentation, og det har fremragende faciliteter til dokumentation af softwareprojekter i en række sprog. Her er nogle funktioner:
- Outputformater: HTML (herunder Windows HTML Help), LaTeX (for printbare PDF-versioner), ePub, Texinfo, manualsider, almindelig tekst.
- Omfattende krydsreferencer: semantisk markering og automatiske links til funktioner, klasser, citater, glossarudtryk og lignende oplysninger.
- Hierarkisk struktur: nem definition af et dokumenttræ, med automatiske links til søskende, forældre og børn.