Правильна документація коду є важливим, але часто забутим аспектом розробки програмного забезпечення. Як розробник, ви звикнете писати чистий, ефективний код, але у вас може бути менше досвіду в написанні хорошої документації.
Хороша документація стане в нагоді всім, хто працює з вашим кодом, будь то інші члени вашої команди чи ви самі пізніше. Це може пояснити, чому ви реалізували щось певним чином або як використовувати певну функцію чи API.
Для розробників JavaScript JSDoc — хороший спосіб почати документувати свій код.
Що таке JSDoc?
Документування коду може бути складним і виснажливим. Проте все більше людей визнають переваги підходу «документи як код», і багато мов мають бібліотеки, які допомагають автоматизувати процес. Для простої, чіткої та короткої документації. Так само, як мова Go має GoDoc для автоматизації документації з коду, так і JavaScript має JSDoc.
JSDoc створює документацію, інтерпретуючи спеціальні коментарі у вашому вихідному коді JavaScript, обробляючи ці коментарі та створюючи документацію на замовлення. Потім ця документація стає доступною у доступному форматі HTML.
Це зберігає документацію в коді, тому, коли ви оновлюєте свій код, документацію легко оновити.
Налаштування JSDoc
Творці JSDoc полегшили початок і налаштування JSDoc у вашому проекті JavaScript.
Щоб інсталювати JSDoc локально, запустіть:
npm install --save-dev jsdoc
Це встановить бібліотеку у вашому проекті як залежність від розробника.
Щоб використовувати JSDoc, ви будете використовувати спеціальні синтаксичні коментарі у вихідному коді. Ви будете писати всі свої коментарі до документації між маркерами /** і */. У них можна описати визначені змінні, функції, параметри функцій та багато іншого.
Наприклад:
* Gets User by name.
* @param {string} name - The name of the User
* @returns {string} User
*/function getUser(name) {
const User = name;
return User;
}
Теги @param і @returns є двома з багатьох спеціальних ключових слів, які JSDoc підтримує для пояснення вашого коду.
Щоб створити документацію для цього коду, запустіть npx jsdoc і вкажіть шлях до вашого файлу JavaScript.
Наприклад:
npx jsdoc src/main.js
Якщо ви встановили JSDoc глобально, ви можете опустити прапорець npx і виконати:
Ця команда створить вихідну папку в корені вашого проекту. Усередині папки ви знайдете файли HTML, які представляють сторінки вашої документації.
Ви можете переглянути документацію, налаштувавши локальний веб-сервер для її розміщення, або просто відкривши файл out/index.html у браузері. Ось приклад того, як буде виглядати сторінка документації за замовчуванням:
Налаштування виводу JSDoc
Ви можете створити файл конфігурації, щоб змінити типову поведінку JSDoc.
Для цього створіть файл conf.js і експортуйте в нього модуль JavaScript.
Наприклад:
module.exports = {
source: {
includePattern: ".+\\\\.js(doc|x)?$",
excludePattern: ["node_modules"],
},
recurseDepth: 5,
sourceType: "module",
opts: {
template: "path/to/template",
destination: "./docs/",
recurse: true,
},
};
Всередині файлу конфігурації є різні Конфігурація JSDoc параметри. Опція шаблону дозволяє використовувати шаблон для налаштування зовнішнього вигляду документації. Спільнота JSDoc надає багато шаблони що ви можете використовувати. Пакет також дозволяє створювати власні персоналізовані шаблони.
Щоб змінити місце розташування згенерованої документації, установіть параметр конфігурації призначення на каталог. У прикладі вище вказано папку документів у корені проекту.
Використовуйте цю команду, щоб запустити JSDoc із файлом конфігурації:
jsdoc -c /path/to/conf.js
Щоб полегшити виконання цієї команди, додайте її як запис сценаріїв у файл package.json:
"scripts": {
"dev": "nodemon app.js",
"run-docs": "jsdoc -c /path/to/conf.js"
},
Тепер ви можете запустити команду сценарію npm всередині терміналу.
Приклад документації, створеної за допомогою JSDoc
Нижче наведена проста арифметична бібліотека з методами додавання та віднімання.
Це приклад добре задокументованого коду JavaScript:
* 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 надають чіткий і вичерпний опис бібліотеки та її методів, зокрема:
- Опис бібліотеки та її призначення.
- Параметри кожного методу, включаючи їх тип і короткий опис.
- Значення та тип, які повертає кожен метод.
- Помилки, які може викликати кожен метод, і умови, які їх викликають.
- Приклад використання кожного методу.
Коментарі також містять тег @module, щоб вказати, що цей файл є модулем, і тег @example, щоб надати приклад коду для кожного методу.
Правильне документування коду розробника
Як бачите, JSDoc є дуже корисним інструментом, який допоможе вам розпочати документування коду JavaScript. Завдяки легкій інтеграції ви можете швидко створювати детальну документацію під час написання коду. Ви також можете підтримувати та оновлювати документацію прямо у своїй робочій області.
Однак, якою б корисною не була автоматизація JSDoc, ви все одно повинні дотримуватися певних вказівок, щоб створити якісну документацію.