Riktig kodedokumentasjon er et viktig, men ofte oversett aspekt ved programvareutvikling. Som utvikler vil du være vant til å skrive ren, effektiv kode, men du har kanskje mindre erfaring med å skrive god dokumentasjon.
God dokumentasjon er nyttig for alle som jobber med koden din, enten det er andre medlemmer av teamet ditt, eller deg selv på et senere tidspunkt. Det kan forklare hvorfor du har implementert noe på en bestemt måte eller hvordan du bruker en bestemt funksjon eller API.
For JavaScript-utviklere er JSDoc en god måte å begynne å dokumentere koden på.
Innholdsfortegnelse
Hva er JSDoc?
Å dokumentere kode kan være komplisert og kjedelig. Flere mennesker erkjenner imidlertid fordelene med en «dokumenter som kode»-tilnærming, og mange språk har biblioteker som hjelper til med å automatisere prosessen. For enkel, klar og konsis dokumentasjon. Akkurat som Go-språket har GoDoc for å automatisere dokumentasjon fra kode, så har JavaScript JSDoc.
JSDoc genererer dokumentasjon ved å tolke spesielle kommentarer i JavaScript-kildekoden din, behandle disse kommentarene og produsere skreddersydd dokumentasjon. Den gjør deretter denne dokumentasjonen tilgjengelig i et tilgjengelig HTML-format.
Dette holder dokumentasjonen innenfor koden, så når du oppdaterer koden din, er det enkelt å oppdatere dokumentasjonen.
Sette opp JSDoc
Skaperne av JSDoc har gjort det enkelt å komme i gang og sette opp JSDoc i JavaScript-prosjektet ditt.
For å installere JSDoc lokalt, kjør:
npm install --save-dev jsdoc
Dette vil installere biblioteket i prosjektet ditt som en utviklingsavhengighet.
For å bruke JSDoc, vil du bruke spesielle syntakskommentarer inne i kildekoden. Du vil skrive alle dokumentasjonskommentarene dine innenfor /**- og */-markørene. Inne i disse kan du beskrive definerte variabler, funksjoner, funksjonsparametere og mye annet.
For eksempel:
* Gets User by name.
* @param {string} name - The name of the User
* @returns {string} User
*/function getUser(name) {
const User = name;
return User;
}
@param og @returns-taggene er to av de mange spesielle nøkkelordene som JSDoc støtter for å forklare koden din.
For å generere dokumentasjonen for denne koden, kjør npx jsdoc etterfulgt av banen til JavaScript-filen.
For eksempel:
npx jsdoc src/main.js
Hvis du installerte JSDoc globalt, kan du utelate npx-flagget og kjøre:
Denne kommandoen vil generere en ut-mappe i prosjektroten. Inne i mappen finner du HTML-filer som representerer sidene i dokumentasjonen din.
Du kan se dokumentasjonen ved å sette opp en lokal webserver for å være vert for den, eller ganske enkelt ved å åpne out/index.html-filen i en nettleser. Her er et eksempel på hvordan en dokumentasjonsside vil se ut som standard:
Konfigurere JSDoc-utgangen
Du kan opprette en konfigurasjonsfil for å endre standardoppførselen til JSDoc.
For å gjøre det, lag en conf.js-fil og eksporter en JavaScript-modul i denne filen.
For eksempel:
module.exports = {
source: {
includePattern: ".+\\\\.js(doc|x)?$",
excludePattern: ["node_modules"],
},
recurseDepth: 5,
sourceType: "module",
opts: {
template: "path/to/template",
destination: "./docs/",
recurse: true,
},
};
Inne i konfigurasjonsfilen er det forskjellige JSDoc-konfigurasjon alternativer. Malalternativet lar deg bruke en mal for å tilpasse dokumentasjonens utseende. JSDocs fellesskap gir mange maler som du kan bruke. Pakken lar deg også lage dine egne personlige maler.
For å endre plasseringen til den genererte dokumentasjonen, sett destinasjonskonfigurasjonsalternativet til en katalog. Eksemplet ovenfor spesifiserer en docs-mappe i prosjektets rot.
Bruk denne kommandoen til å kjøre JSDoc med en konfigurasjonsfil:
jsdoc -c /path/to/conf.js
For å gjøre det enklere å kjøre denne kommandoen, legg den til som en skriptoppføring i filen package.json:
"scripts": {
"dev": "nodemon app.js",
"run-docs": "jsdoc -c /path/to/conf.js"
},
Du kan nå kjøre kommandoen npm script inne i en terminal.
Et eksempel på dokumentasjon generert med JSDoc
Nedenfor er et enkelt aritmetisk bibliotek med addisjons- og subtraheremetoder.
Dette er et eksempel på godt dokumentert JavaScript-kode:
* A library for performing basic arithmetic operations.
* @module arithmetic
*/
module.exports = {
* Adds two numbers.
* @param {number} a - The first number.
* @param {number} b - The second number.
* @return {number} The sum of the two numbers.
* @throws {TypeError} If any of the arguments is not a number.
*
* @example
* const arithmetic = require('arithmetic');
* const sum = arithmetic.add(5, 10);
* console.log(sum);
*/
add: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
throw new TypeError('Both arguments must be numbers.');
}return a + b;
},
* Subtracts the second number from the first number.
* @param {number} a - The number to subtract from.
* @param {number} b - The number to subtract.
* @return {number} The result of the subtraction.
* @throws {TypeError} If any of the arguments is not a number.
*
* @example
* const arithmetic = require('arithmetic');
* const difference = arithmetic.subtract(10, 5);
* console.log(difference);
*/
subtract: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
throw new TypeError('Both arguments must be numbers.');
}return a - b;
}
};
JSDoc-kommentarene gir en klar og omfattende beskrivelse av biblioteket og dets metoder, inkludert:
- En beskrivelse av biblioteket og dets formål.
- Hver metodes parametere, inkludert deres type og en kort beskrivelse.
- Verdien og typen som hver metode returnerer.
- Feilene som hver metode kan gi og forholdene som forårsaker det.
- Et eksempel på hvordan du bruker hver metode.
Kommentarene inkluderer også @module-taggen for å indikere at denne filen er en modul og @example-taggen for å gi et kodeeksempel for hver metode.
Dokumentere utviklerkode på riktig måte
Som du kan se, er JSDoc et veldig nyttig verktøy for å komme i gang med å dokumentere JavaScript-kode. Med den enkle integrasjonen kan du generere rask og detaljert dokumentasjon mens du skriver koden. Du kan også vedlikeholde og oppdatere dokumentasjonen rett i arbeidsområdet ditt.
Men så nyttig som JSDocs automatisering er, bør du fortsatt følge visse retningslinjer slik at du kan lage kvalitetsdokumentasjon.