Korrekt kodedokumentation er et vigtigt, men ofte overset aspekt af softwareudvikling. Som udvikler vil du være vant til at skrive ren, effektiv kode, men du er måske mindre erfaren i at skrive god dokumentation.
God dokumentation er nyttig for alle, der arbejder med din kode, uanset om det er andre medlemmer af dit team eller dig selv på et senere tidspunkt. Det kan forklare, hvorfor du har implementeret noget på en bestemt måde, eller hvordan du bruger en bestemt funktion eller API.
For JavaScript-udviklere er JSDoc en god måde at begynde at dokumentere din kode på.
Indholdsfortegnelse
Hvad er JSDoc?
Dokumentation af kode kan være komplekst og kedeligt. Men flere mennesker anerkender fordelene ved en “dokumenter som kode”-tilgang, og mange sprog har biblioteker, der hjælper med at automatisere processen. For enkel, klar og kortfattet dokumentation. Ligesom Go-sproget har GoDoc til at automatisere dokumentation fra kode, så har JavaScript JSDoc.
JSDoc genererer dokumentation ved at fortolke specielle kommentarer i din JavaScript-kildekode, behandle disse kommentarer og producere skræddersyet dokumentation. Det gør derefter denne dokumentation tilgængelig i et tilgængeligt HTML-format.
Dette holder dokumentationen i koden, så når du opdaterer din kode, er det nemt at opdatere dokumentationen.
Opsætning af JSDoc
Skaberne af JSDoc har gjort det nemt at komme i gang og opsætte JSDoc i dit JavaScript-projekt.
For at installere JSDoc lokalt skal du køre:
npm install --save-dev jsdoc
Dette vil installere biblioteket i dit projekt som en dev-afhængighed.
For at bruge JSDoc skal du bruge specielle syntakskommentarer i din kildekode. Du vil skrive alle dine dokumentationskommentarer inden for /** og */ markører. Inde i disse kan du beskrive definerede variabler, funktioner, funktionsparametre og meget andet.
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 tags er to af de mange specielle nøgleord, som JSDoc understøtter for at forklare din kode.
For at generere dokumentationen til denne kode skal du køre npx jsdoc efterfulgt af stien til din JavaScript-fil.
For eksempel:
npx jsdoc src/main.js
Hvis du installerede JSDoc globalt, kan du udelade npx-flaget og køre:
Denne kommando vil generere en ud-mappe i dit projektrod. Inde i mappen finder du HTML-filer, der repræsenterer siderne i din dokumentation.
Du kan se dokumentationen ved at konfigurere en lokal webserver til at være vært for den, eller blot ved at åbne out/index.html-filen inde i en browser. Her er et eksempel på, hvordan en dokumentationsside vil se ud som standard:
Konfiguration af JSDoc-output
Du kan oprette en konfigurationsfil for at ændre JSDocs standardadfærd.
For at gøre det skal du oprette en conf.js-fil og eksportere et JavaScript-modul i denne fil.
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,
},
};
Inde i konfigurationsfilen er der forskellige JSDoc-konfiguration muligheder. Skabelonindstillingen lader dig bruge en skabelon til at tilpasse dokumentationens udseende. JSDocs fællesskab giver mange skabeloner som du kan bruge. Pakken giver dig også mulighed for at oprette dine egne personlige skabeloner.
For at ændre placeringen af den genererede dokumentation skal du indstille destinationskonfigurationsindstillingen til en mappe. Eksemplet ovenfor angiver en docs-mappe i projektets rod.
Brug denne kommando til at køre JSDoc med en konfigurationsfil:
jsdoc -c /path/to/conf.js
For at gøre det nemmere at køre denne kommando skal du tilføje den som en script-indgang i din package.json-fil:
"scripts": {
"dev": "nodemon app.js",
"run-docs": "jsdoc -c /path/to/conf.js"
},
Du kan nu køre kommandoen npm script inde i en terminal.
Et eksempel på dokumentation genereret med JSDoc
Nedenfor er et simpelt aritmetisk bibliotek med add og subtraher metoder.
Dette er et eksempel på veldokumenteret 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-kommentarerne giver en klar og omfattende beskrivelse af biblioteket og dets metoder, herunder:
- En beskrivelse af biblioteket og dets formål.
- Hver metodes parametre, herunder deres type og en kort beskrivelse.
- Værdien og typen, som hver metode returnerer.
- De fejl, som hver metode kan give, og de forhold, der forårsager det.
- Et eksempel på, hvordan man bruger hver metode.
Kommentarerne inkluderer også @module-tagget for at angive, at denne fil er et modul, og @example-tagget for at give et kodeeksempel for hver metode.
Dokumentation af udviklerkode på den rigtige måde
Som du kan se, er JSDoc et meget nyttigt værktøj til at få dig i gang med at dokumentere JavaScript-kode. Med dens nemme integration kan du generere hurtig og detaljeret dokumentation, mens du skriver din kode. Du kan også vedligeholde og opdatere dokumentationen direkte i dit arbejdsområde.
Men lige så nyttig som JSDocs automatisering er, bør du stadig overholde visse retningslinjer, så du kan oprette kvalitetsdokumentation.