مستندسازی کد مناسب برای نگهداری ضروری است. با استفاده از JSDocs، می‌توانید آن را مستقیماً در کد خود جاسازی کنید تا همیشه در دسترس باشد.
مستندسازی کد مناسب یکی از جنبه های مهم توسعه نرم افزار است که اغلب نادیده گرفته می شود. به عنوان یک توسعه دهنده، به نوشتن کدهای تمیز و کارآمد عادت دارید، اما ممکن است در نوشتن اسناد خوب تجربه کمتری داشته باشید.
اسناد خوب برای هر کسی که با کد شما کار می کند مفید است، خواه سایر اعضای تیم شما باشند، یا خود شما، در تاریخ بعدی. می تواند توضیح دهد که چرا چیزی را به روشی خاص پیاده سازی کرده اید یا چگونه از یک تابع یا API خاص استفاده کنید.
برای توسعه دهندگان جاوا اسکریپت، JSDoc راه خوبی برای شروع مستندسازی کد شماست.
JSDoc چیست؟
کد مستندسازی می تواند پیچیده و خسته کننده باشد. با این حال، افراد بیشتری مزایای رویکرد «اسناد به‌عنوان کد» را می‌شناسند و بسیاری از زبان‌ها دارای کتابخانه‌هایی هستند که به خودکارسازی فرآیند کمک می‌کنند. برای مستندات ساده، واضح و مختصر. درست مانند زبان Go برای خودکارسازی اسناد از روی کد، GoDoc دارد، جاوا اسکریپت نیز دارای JSDoc است.
JSDoc با تفسیر نظرات خاص در کد منبع جاوا اسکریپت، پردازش این نظرات و تولید اسناد سفارشی، مستندات را تولید می کند. سپس این اسناد را در قالب HTML قابل دسترس در دسترس قرار می دهد.
این اسناد را در داخل کد نگه می‌دارد، بنابراین وقتی کد خود را به‌روزرسانی می‌کنید، به‌روزرسانی مستندات آسان است.
راه اندازی JSDoc
سازندگان JSDoc شروع و راه اندازی JSDoc را در پروژه جاوا اسکریپت شما آسان کرده اند.
برای نصب JSDoc به صورت محلی، اجرا کنید:
npm install --save-dev jsdoc
با این کار کتابخانه شما به عنوان وابستگی توسعه دهنده در پروژه شما نصب می شود.
نحوه نوشتن نظرات 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 را به دنبال مسیر فایل جاوا اسکریپت خود اجرا کنید.
مثلا:
npx jsdoc src/main.js
اگر JSDoc را به صورت سراسری نصب کرده اید، می توانید پرچم npx را حذف کرده و اجرا کنید:
jsdoc path/to/file.js
این دستور یک پوشه out در ریشه پروژه شما ایجاد می کند. در داخل پوشه، فایل های HTML را خواهید دید که نمایانگر صفحات اسناد شما هستند.
می توانید اسناد را با راه اندازی یک وب سرور محلی برای میزبانی آن، یا به سادگی با باز کردن فایل out/index.html در یک مرورگر مشاهده کنید. در اینجا نمونه‌ای از این است که صفحه اسناد به طور پیش‌فرض چگونه خواهد بود:
پیکربندی خروجی JSDoc
می توانید یک فایل پیکربندی برای تغییر رفتار پیش فرض JSDoc ایجاد کنید.
برای انجام این کار، یک فایل conf.js ایجاد کنید و یک ماژول جاوا اسکریپت را در داخل این فایل صادر کنید.
مثلا:
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 الگوهای زیادی را ارائه می دهد که می توانید از آنها استفاده کنید. این بسته همچنین به شما امکان می دهد تا قالب های شخصی سازی شده خود را ایجاد کنید.
برای تغییر مکان مستندات تولید شده، گزینه پیکربندی مقصد را روی دایرکتوری تنظیم کنید. مثال بالا یک پوشه docs را در ریشه پروژه مشخص می کند.
از این دستور برای اجرای JSDoc با یک فایل پیکربندی استفاده کنید:
jsdoc -c /path/to/conf.js
برای سهولت در اجرای این دستور، آن را به عنوان ورودی اسکریپت در فایل package.json خود اضافه کنید:
"scripts": {
"dev": "nodemon app.js",
"run-docs": "jsdoc -c /path/to/conf.js"
},
اکنون می توانید دستور npm script را در یک ترمینال اجرا کنید.
نمونه ای از اسناد تولید شده با JSDoc
در زیر یک کتابخانه محاسباتی ساده با روش های جمع و تفریق آورده شده است.
این نمونه ای از کد جاوا اسکریپت مستند شده است:
/**
* 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); // 15
*/
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); // 5
*/
subtract: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
throw new TypeError('Both arguments must be numbers.');
}
return a - b;
}
// ... other methods ...
};
نظرات JSDoc شرح واضح و جامعی از کتابخانه و روش های آن ارائه می دهد، از جمله:
- شرحی از کتابخانه و هدف آن.
- پارامترهای هر روش، از جمله نوع آنها و توضیح مختصری.
- مقدار و نوع که هر متد برمی گرداند.
- خطاهایی که هر روش می تواند ایجاد کند و شرایطی که باعث آن می شود.
- مثالی از نحوه استفاده از هر روش.
نظرات همچنین شامل تگ @module برای نشان دادن اینکه این فایل یک ماژول است و تگ @example برای ارائه یک نمونه کد برای هر روش می باشد.
مستندسازی کد برنامه‌نویس به روش صحیح
همانطور که می بینید، JSDoc یک ابزار بسیار مفید برای شروع مستندسازی کد جاوا اسکریپت است. با یکپارچه‌سازی آسان آن، می‌توانید مستندات سریع و دقیق را هنگام نوشتن کد خود ایجاد کنید. همچنین می توانید اسناد را مستقیماً در فضای کاری خود نگهداری و به روز کنید.
با این حال، همانطور که اتوماسیون JSDoc مفید است، همچنان باید دستورالعمل های خاصی را رعایت کنید تا بتوانید مستندات با کیفیت ایجاد کنید.