Належна документація програмного коду є надзвичайно важливим, хоча й часто ігнорованим аспектом розробки програмних продуктів. Розробники зазвичай зосереджуються на написанні чіткого та ефективного коду, проте навичкам створення якісної документації може приділятися менше уваги.
Якісна документація є цінною для всіх, хто працює з вашим кодом, незалежно від того, чи це колеги по команді, чи ви самі в майбутньому. Вона пояснює, чому певні рішення реалізовано саме так, а також детально описує використання певних функцій або API.
Для розробників на JavaScript, JSDoc є чудовим інструментом для початку документування власного коду.
Що таке JSDoc?
Процес документування коду може бути складним і виснажливим. Однак, все більше розробників усвідомлюють переваги підходу “документація як код”, і для багатьох мов програмування існують бібліотеки, які допомагають автоматизувати цей процес. JSDoc, подібно до GoDoc для мови Go, забезпечує просте, зрозуміле та лаконічне рішення для автоматизації документації у JavaScript.
JSDoc генерує документацію шляхом аналізу спеціальних коментарів, вбудованих у вихідний код JavaScript. Ці коментарі обробляються і перетворюються у зручну HTML-документацію.
Таким чином, документація залишається інтегрованою з кодом, що робить її оновлення одночасно зі змінами у коді набагато простішим.
Налаштування JSDoc
Розробники JSDoc максимально спростили процес початку роботи з інструментом та його інтеграцію у ваші JavaScript проєкти.
Щоб встановити JSDoc локально, скористайтеся командою:
npm install --save-dev jsdoc
Ця команда додасть бібліотеку до вашого проєкту як залежність розробника.
JSDoc використовує спеціальні синтаксичні коментарі у вихідному коді для створення документації. Коментарі, призначені для документації, повинні бути в межах маркерів /** та */. У цих коментарях можна описати оголошені змінні, функції, параметри функцій та багато іншого.
Наприклад:
* Отримує користувача за іменем.
* @param {string} name - Ім'я користувача
* @returns {string} Користувач
*/function getUser(name) {
const User = name;
return User;
}
Теги @param і @returns – це лише два приклади з багатьох спеціальних ключових слів, які JSDoc використовує для пояснення коду.
Для генерації документації на основі цього коду, виконайте команду npx jsdoc, вказавши шлях до вашого JavaScript файлу.
Наприклад:
npx jsdoc src/main.js
Якщо JSDoc встановлено глобально, можна пропустити префікс npx і виконати:
Ця команда створить папку “out” у кореневому каталозі вашого проєкту. Усередині цієї папки ви знайдете 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. Опція “template” дозволяє використовувати шаблон для налаштування зовнішнього вигляду документації. Спільнота JSDoc пропонує велику кількість шаблонів, які можна використовувати. Крім того, пакет дозволяє створювати власні, персоналізовані шаблони.
Щоб змінити місце збереження згенерованої документації, встановіть параметр конфігурації “destination” на потрібний каталог. У наведеному вище прикладі, документація буде зберігатися у папці “docs” в корені проєкту.
Для запуску 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:
* Бібліотека для виконання базових арифметичних операцій.
* @module arithmetic
*/
module.exports = {
* Додає два числа.
* @param {number} a - Перше число.
* @param {number} b - Друге число.
* @return {number} Сума двох чисел.
* @throws {TypeError} Якщо будь-який з аргументів не є числом.
*
* @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('Обидва аргументи мають бути числами.');
}return a + b;
},
* Віднімає друге число від першого.
* @param {number} a - Число, від якого віднімається.
* @param {number} b - Число, яке віднімається.
* @return {number} Результат віднімання.
* @throws {TypeError} Якщо будь-який з аргументів не є числом.
*
* @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('Обидва аргументи мають бути числами.');
}return a - b;
}
};
Коментарі JSDoc забезпечують чіткий і вичерпний опис бібліотеки та її методів, зокрема:
- Опис бібліотеки та її призначення.
- Параметри кожного методу, включаючи їхній тип і короткий опис.
- Значення та тип, які повертає кожен метод.
- Помилки, які може викликати кожен метод, та умови, за яких вони виникають.
- Приклад використання кожного методу.
Коментарі також містять тег @module, щоб вказати, що цей файл є модулем, та тег @example, щоб надати приклад коду для кожного методу.
Правильне документування коду розробника
Як бачите, JSDoc є дуже корисним інструментом для початку документування коду JavaScript. Завдяки легкій інтеграції ви можете швидко створювати детальну документацію безпосередньо під час написання коду. Крім того, ви можете підтримувати та оновлювати документацію прямо у вашому робочому середовищі.
Проте, незалежно від того, наскільки корисним є автоматизація JSDoc, необхідно дотримуватися певних рекомендацій для створення якісної документації.