Documentarea corectă a codului este un aspect important, dar adesea trecut cu vederea, al dezvoltării software. În calitate de dezvoltator, veți fi obișnuit să scrieți cod curat și eficient, dar este posibil să aveți mai puțină experiență în scrierea unei documentații bune.
O documentație bună este utilă pentru oricine lucrează cu codul dvs., fie că este vorba de alți membri ai echipei dvs. sau de dvs., la o dată ulterioară. Poate explica de ce ați implementat ceva într-un anumit mod sau cum să utilizați o anumită funcție sau API.
Pentru dezvoltatorii JavaScript, JSDoc este o modalitate bună de a începe să vă documentați codul.
Cuprins
Ce este JSDoc?
Documentarea codului poate fi complexă și plictisitoare. Cu toate acestea, mai mulți oameni recunosc beneficiile unei abordări „docs ca cod”, iar multe limbi au biblioteci care ajută la automatizarea procesului. Pentru o documentare simplă, clară și concisă. La fel cum limbajul Go are GoDoc pentru a automatiza documentația din cod, la fel JavaScript are JSDoc.
JSDoc generează documentație interpretând comentarii speciale în codul sursă JavaScript, procesând aceste comentarii și producând documentație personalizată. Apoi face această documentație disponibilă într-un format HTML accesibil.
Acest lucru păstrează documentația în cod, astfel încât atunci când actualizați codul, este ușor să actualizați documentația.
Configurarea JSDoc
Creatorii JSDoc au făcut mai ușor să începeți și să configurați JSDoc în proiectul dvs. JavaScript.
Pentru a instala JSDoc local, rulați:
npm install --save-dev jsdoc
Aceasta va instala biblioteca în proiectul dvs. ca dependență de dezvoltare.
Pentru a utiliza JSDoc, veți folosi comentarii speciale de sintaxă în codul sursă. Veți scrie toate comentariile de documentare în marcatoarele /** și */. În interiorul acestora, puteți descrie variabile definite, funcții, parametrii funcției și multe altele.
De exemplu:
* Gets User by name.
* @param {string} name - The name of the User
* @returns {string} User
*/function getUser(name) {
const User = name;
return User;
}
Etichetele @param și @returns sunt două dintre multele cuvinte cheie speciale pe care le acceptă JSDoc pentru a vă explica codul.
Pentru a genera documentația pentru acest cod, rulați npx jsdoc urmat de calea către fișierul JavaScript.
De exemplu:
npx jsdoc src/main.js
Dacă ați instalat JSDoc la nivel global, puteți omite marcajul npx și rulați:
Această comandă va genera un folder out în rădăcina proiectului. În interiorul folderului, veți găsi fișiere HTML reprezentând paginile documentației dvs.
Puteți vizualiza documentația instalând un server web local pentru a o găzdui sau pur și simplu deschizând fișierul out/index.html în interiorul unui browser. Iată un exemplu despre cum va arăta implicit o pagină de documentație:
Configurarea ieșirii JSDoc
Puteți crea un fișier de configurare pentru a schimba comportamentul implicit al JSDoc.
Pentru a face acest lucru, creați un fișier conf.js și exportați un modul JavaScript în interiorul acestui fișier.
De exemplu:
module.exports = {
source: {
includePattern: ".+\\\\.js(doc|x)?$",
excludePattern: ["node_modules"],
},
recurseDepth: 5,
sourceType: "module",
opts: {
template: "path/to/template",
destination: "./docs/",
recurse: true,
},
};
În interiorul fișierului de configurare sunt diverse Configurare JSDoc Opțiuni. Opțiunea de șablon vă permite să utilizați un șablon pentru a personaliza aspectul documentației. Comunitatea JSDoc oferă multe șabloane pe care le poți folosi. Pachetul vă permite, de asemenea, să vă creați propriile șabloane personalizate.
Pentru a schimba locația documentației generate, setați opțiunea de configurare a destinației la un director. Exemplul de mai sus specifică un folder de documente în rădăcina proiectului.
Utilizați această comandă pentru a rula JSDoc cu un fișier de configurare:
jsdoc -c /path/to/conf.js
Pentru a ușura rularea acestei comenzi, adăugați-o ca intrare de script în fișierul package.json:
"scripts": {
"dev": "nodemon app.js",
"run-docs": "jsdoc -c /path/to/conf.js"
},
Acum puteți rula comanda script-ului npm în interiorul unui terminal.
Un exemplu de documentație generată cu JSDoc
Mai jos este o bibliotecă aritmetică simplă cu metode de adunare și scădere.
Acesta este un exemplu de cod JavaScript bine documentat:
* 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;
}
};
Comentariile JSDoc oferă o descriere clară și cuprinzătoare a bibliotecii și a metodelor acesteia, inclusiv:
- O descriere a bibliotecii și a scopului acesteia.
- Parametrii fiecărei metode, inclusiv tipul lor și o scurtă descriere.
- Valoarea și tipul pe care le returnează fiecare metodă.
- Erorile pe care le poate arunca fiecare metodă și condițiile care le provoacă.
- Un exemplu de utilizare a fiecărei metode.
Comentariile includ, de asemenea, eticheta @module pentru a indica faptul că acest fișier este un modul și eticheta @example pentru a oferi un exemplu de cod pentru fiecare metodă.
Documentarea codului de dezvoltator în mod corect
După cum puteți vedea, JSDoc este un instrument foarte util pentru a începe să documentați codul JavaScript. Cu integrarea sa ușoară, puteți genera documentație rapidă și detaliată pe măsură ce scrieți codul. De asemenea, puteți întreține și actualiza documentația chiar în spațiul dvs. de lucru.
Cu toate acestea, oricât de utilă este automatizarea lui JSDoc, ar trebui să respectați în continuare anumite reguli, astfel încât să puteți crea documentație de calitate.