Att skapa välskriven koddokumentation är en väsentlig, men ofta åsidosatt del av mjukvaruutvecklingsprocessen. Som programmerare är du troligen van vid att producera ren och effektiv kod, men kanske mindre erfaren i konsten att skriva förstklassig dokumentation.
Utmärkt dokumentation är värdefull för alla som interagerar med din kod, oavsett om det handlar om andra medlemmar i ditt team eller till och med dig själv vid ett senare tillfälle. Den kan tydligt förklara varför du valt en specifik implementeringsmetod, eller hur en viss funktion eller ett API ska användas.
För JavaScript-utvecklare utgör JSDoc en utmärkt utgångspunkt för att påbörja dokumentationsarbetet.
Vad är JSDoc?
Att dokumentera kod kan upplevas som både komplext och tidskrävande. Allt fler inser emellertid fördelarna med en ”dokumentation som kod”-metodik, och många programmeringsspråk tillhandahåller bibliotek som hjälper till att automatisera processen. För att skapa enkel, klar och koncis dokumentation har JavaScript JSDoc, precis som Go-språket har GoDoc för att automatisera dokumentationsprocessen från källkoden.
JSDoc genererar dokumentation genom att tolka särskilda kommentarer i din JavaScript-kod. Dessa kommentarer bearbetas, och ut kommer skräddarsydd dokumentation. Dokumentationen levereras sedan i ett användarvänligt HTML-format.
Denna metod håller dokumentationen nära koden, vilket gör det smidigt att uppdatera dokumentationen i takt med att koden utvecklas.
Konfigurera JSDoc
Skaparna av JSDoc har gjort det lätt att börja använda och installera JSDoc i ditt JavaScript-projekt.
För att installera JSDoc lokalt, kör följande kommando:
npm install --save-dev jsdoc
Detta lägger till biblioteket som ett utvecklingsberoende i ditt projekt.
För att använda JSDoc, kommer du att använda speciell syntax för kommentarer i din kod. Alla dina dokumentationskommentarer ska skrivas inom markörerna /** och */. Inom dessa markörer kan du beskriva variabler, funktioner, funktionsparametrar och mycket mer.
Ett exempel:
* Hämtar användare med namn.
* @param {string} name - Användarens namn
* @returns {string} Användare
*/
function getUser(name) {
const User = name;
return User;
}
Taggar som @param och @returns är två exempel på de många speciella nyckelord som JSDoc erbjuder för att förklara din kod.
För att generera dokumentationen för den här koden, kör kommandot npx jsdoc följt av sökvägen till din JavaScript-fil.
Exempel:
npx jsdoc src/main.js
Om du installerat JSDoc globalt kan du utelämna npx-flaggan och köra:
Detta kommando skapar en mapp vid namn ”out” i din projektmapp. I denna mapp hittar du HTML-filer som motsvarar sidorna i din dokumentation.
Du kan visa dokumentationen genom att antingen ställa in en lokal webbserver som värd eller genom att öppna filen out/index.html direkt i webbläsaren. Här är ett exempel på hur en dokumentationssida kan se ut med standardinställningarna:
Konfigurera JSDoc-utdata
Du har möjlighet att skapa en konfigurationsfil för att justera JSDocs standardbeteende.
För att göra detta, skapa en fil som heter conf.js och exportera en JavaScript-modul i denna fil.
Här är ett exempel:
module.exports = {
source: {
includePattern: ".+\\\\.js(doc|x)?$",
excludePattern: ["node_modules"],
},
recurseDepth: 5,
sourceType: "module",
opts: {
template: "path/to/template",
destination: "./docs/",
recurse: true,
},
};
Inuti konfigurationsfilen finns diverse JSDoc-konfigurationsalternativ. Template-alternativet tillåter dig att applicera en mall för att anpassa dokumentationens design. JSDocs community erbjuder ett flertal mallar som du kan nyttja. Paketet ger även möjligheten att skapa dina egna unika mallar.
För att modifiera platsen där den genererade dokumentationen ska lagras, ställ in destinationskonfigurationsalternativet till en relevant katalog. Exemplet ovan specificerar en mapp kallad ”docs” i projektets rot.
Använd följande kommando för att köra JSDoc med en konfigurationsfil:
jsdoc -c /path/to/conf.js
För att förenkla hanteringen av detta kommando, kan du lägga till det som ett skript i din package.json-fil:
"scripts": {
"dev": "nodemon app.js",
"run-docs": "jsdoc -c /path/to/conf.js"
},
Nu kan du köra kommandot npm script direkt i din terminal.
Ett exempel på dokumentation genererad med JSDoc
Nedan följer ett simpelt aritmetiskt bibliotek med metoder för addition och subtraktion.
Det här är ett exempel på välkommenterad JavaScript-kod:
* Ett bibliotek för att utföra grundläggande aritmetiska operationer.
* @module arithmetic
*/
module.exports = {
* Adderar två tal.
* @param {number} a - Det första talet.
* @param {number} b - Det andra talet.
* @return {number} Summan av de två talen.
* @throws {TypeError} Om någon av argumenten inte är ett tal.
*
* @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('Båda argumenten måste vara tal.');
}
return a + b;
},
* Subtraherar det andra talet från det första talet.
* @param {number} a - Talet att subtrahera från.
* @param {number} b - Talet att subtrahera.
* @return {number} Resultatet av subtraktionen.
* @throws {TypeError} Om någon av argumenten inte är ett tal.
*
* @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('Båda argumenten måste vara tal.');
}
return a - b;
}
};
JSDoc-kommentarerna ger en tydlig och omfattande beskrivning av biblioteket och dess metoder, inklusive:
- En beskrivning av biblioteket och dess användningsområde.
- Varje metods parametrar, deras datatyp och en kort beskrivning.
- Det värde och datatyp som varje metod returnerar.
- De eventuella fel som varje metod kan generera och omständigheterna som orsakar dessa fel.
- Ett exempel som illustrerar hur varje metod används.
Kommentarerna inkluderar även @module-taggen för att indikera att denna fil är en modul, samt @example-taggen för att tillhandahålla ett kodexempel för varje metod.
Dokumentera utvecklarkoden på rätt sätt
Som du ser är JSDoc ett mycket praktiskt verktyg för att komma igång med dokumentation av JavaScript-kod. Med enkel integration kan du skapa snabb och detaljerad dokumentation under kodningsprocessen. Du kan också underhålla och uppdatera dokumentationen direkt i din arbetsyta.
Trots JSDocs automatiseringsförmåga, är det viktigt att följa vissa riktlinjer för att säkerställa kvaliteten på din dokumentation.