مستند‌سازی نرم افزار

مستندسازی نرم افزار (Software Documentation) یکی از بخش‌های مهم در فرایند توسعه نرم‌افزار است که به بهبود تعامل بین توسعه‌دهندگان یک پروژه، بهبود کیفیت سیستم و افزایش قابلیت توسعه و نگهداری سیستم کمک می‌کند. به طور کلی، می‌توان مستندسازی نرم‌افزار (یا همان داکیومنت‌نویسی) را به دو دسته مستندات فنی و مستندات مربوط به راه‌اندازی و استفاده تقسیم کرد:

• مستندات فنی آن دسته از مستندات هستند که توسط اعضای تیم فنی تهیه می‌شوند و شامل توضیحاتی درباره‌ی ساختار، معماری، طراحی دیتابیس و دیگر ویژگی‌های فنی سیستم هستند.
• مستندات راه‌اندازی و استفاده، مستنداتی هستند که برای کاربران نهایی تهیه می‌شوند و نحوه نصب و کار با نرم‌افزار را توضیح می‌دهند.

در این مقاله قصد داریم به معرفی انواع مختلف مستندات فنی و ابزار‌های پرکاربرد در تهیه آن‌ها بپردازیم.

۱. مستند SRS

مستند SRS یا همان Software Requirements Specification ، مربوط به ویژگی‌ها و نیازمندی‌های سیستم نرم‌افزاری است و به طور دقیق مشخص می‌کند که سیستم چه ویژگی‌هایی دارد و باید چه نیازمندی‌هایی را فراهم کند. دو نمونه از موارد مهمی که باید در این مستند ذکر شوند نیازمندی‌های functional و non-functional هستند:

• در نیازمندی‌های functional باید رفتار و ویژگی‌های مورد انتظار سیستم به طور دقیق مشخص شوند. برای این کار باید برای هر نیازمندی؛ ورودی‌ها، خروجی‌ها، پیش شرط‌ها و پس شرط‌ها و کاربرانی که اجازه دسترسی به این ویژگی‌ دارند به طور دقیق مستند شوند.
• نیازمندی‌های non-functional به ویژگی‌های کیفی سیستم مانند امنیت، قابلیت اطمینان، کارایی، در دسترس بودن و قابلیت نگهداری سیستم مربوط می‌شوند. برای مستندسازی این نیازمندی‌ها، میزان پشتیبانی سیستم از هر کدام از این ویژگی‌ها مستند می‌شوند.

۲. مستند SDD 

در مستند Software Design Description) SDD) اطلاعات مربوط به ساختار و معماری سیستم مانند دیاگرام‌ها و اطلاعات مربوط به دیتابیس نگهداری می‌شوند. به طور کلی این مستند بیان می‌کند که نیازمندی‌های گفته شده در SRS چگونه توسط سیستم برآورده می‌شوند.

۱.۲. تصویرسازی مستندات با رسم دیاگرام

دیاگرام‌ها به دلیل قابلیت خود در تصویرسازی ساختار و معماری سیستم، اهمیت زیادی دارند. یادگیری و استفاده از دیاگرام‌ها می‌تواند در بهبود کیفیت مستندسازی بسیار تاثیرگذار باشد. برخی از انواع دیاگرام‌ها عبارتند از:

• UML Diagram
• Activity Diagram
• Class Diagram
• Component Diagram

۱.۱.۲. ابزار visual paradigm 

این ابزار یکی از ابزارهای معروف برای رسم دیاگرام‌ها در توسعه نرم‌افزار است که پشتیبانی گسترده‌ای از انواع دیاگرام‌ها می‌کند. برای کار با این ابزار، توسعه‌دهنده باید خودش دیاگرام را به طور کاملا دستی از ابتدا رسم کند که در برخی شرایط می‌تواند کاری زمان‌بر باشد.

۲.۱.۲. ابزار eraser 

این ابزار یک ابزار تحت وب برای رسم دیاگرام با امکان تعامل با هوش مصنوعی است. تعامل با هوش مصنوعی یکی از نقاط قوت این ابزار است و این امکان را فراهم می‌کند که این ابزار با دریافت سناریو، دیاگرام آن را رسم کند اما قطعا دارای خطاهایی است و نمی‌توان تنها با تکیه بر توانایی هوش مصنوعی آن، دیاگرام رسم کرد.

۳.۱.۲. ابزار  mermaid

این ابزار از کد زبان برنامه‌نویسی جاوا اسکریپت برای رسم دیاگرام استفاده می‌کند و دیگر نیازی به رسم اشکال و اتصالات به صورت دستی نیست. این کار احتمال خطا در تعیین روابط بین بخش‌های مختلف دیاگرام را کاهش می‌دهد و رسم دیاگرام با کد برای توسعه دهندگان نیز معمولا راحت‌تر است. mermaid از طریق تعامل با هوش مصنوعی می‌تواند سناریو مربوط به دیاگرام را به صورت متنی دریافت، و دیاگرام آن را رسم کند.

برخی از IDEها دارای پلاگین‌هایی هستند که کار رسم دیاگرام با این ابزار را آسان‌تر می‌کنند. برای مثال VS Code با پلاگین Mermaid Editor امکان نمایش دیاگرام در زمان رسم در ide و ویرایش آن را فراهم می‌کند. این پلاگین همچنین امکان دانلود دیاگرام با فرمت‌های png ،jpg ،webp ،svg را فراهم می‌کند.

ویژگی دیگر این ابزار در این است که برخی از ابزار‌های تولید کننده داکیومنت سورس کد (مانند jsdoc و sphinx) از annotationهای این ابزار پشتیبانی می‌کنند و می‌توان در بلوک‌های مستندنویسی این ابزار‌ها علاوه بر نوشتن توضیحات، دیاگرام نیز رسم کرد.

/**
 * Represents a book.
 * @constructor
 * @param {string} title - The title of the book.
 * @param {string} author - The author of the book.
 *
 * @mermaid
 * graph TD;
 * A-->B;
 * A-->C;
 * B-->D;
 * C-->D;
 */
function Book(title, author) {
  /* ... */
}

۲.۲. مستندسازی دیتابیس 

مستندسازی دیتابیس نیز در توسعه نرم‌افزار اهمیت بسیاری دارد و مانند یک دفترچه راهنما برای اطلاعات مربوط به داده‌های سیستم عمل می‌کند. به طور کلی مستندات مربوط به شمای دیتابیس را می‌توان با ابزارهای رسم دیاگرام نیز ترسیم کرد اما ابزارهایی نیز وجود دارند که به طور تخصصی برای مستندسازی شمای دیتابیس طراحی شده‌اند که در ادامه به بررسی چند نمونه از این ابزارها می‌پردازیم.

۱.۲.۲. ابزار  dbschema 

این ابزار یک ابزار‌ تخصصی برای رسم شمای دیتابیس است که می‌توان از آن برای دیتابیس‌های SQL و NOSQL استفاده کرد. این ابزار، امکاناتی مانند اکسپورت کردن جزئیات (برای مثال ارتباط بین جداول)، دریافت خروجی در فرمت‌های مختلفی مانند html ،jpg ،pdf و رسم شمای دیتابیس به صورت خودکار از طریق اتصال به آن را فراهم می‌کند. این ابزار با پشتیبانی از زبان‌های کوئری‌نویسی می‌تواند به توسعه‌دهندگان در نوشتن کوئری‌های پیچیده کمک کند و توسعه و ویرایش شمای دیتابیس را نیز آسان‌تر کند.

۲.۲.۲. ابزار DataGrip  

ابزار DataGrip برای توسعه‌دهندگانی که با دیتابیس‌های مختلفی کار می‌کنند بسیار مناسب است. امکان اکسپورت کردن جزئیات (برای مثال ارتباط بین جداول) و دریافت خروجی در فرمت‌های مختلفی مانند html ،jpg ،pdf از جمله ویژگی‌های این ابزار است. علاوه بر این، این ابزار تعامل بالایی با ابزار‌های version control مانند git دارد و می‌توان شمای دیتابیس را به طور مستقیم از datagrip به ریپازیتوری گیت وصل کرد تا تغییرات شمای دیتابیس به صورت خودکار به ریپازیتوری گیت اضافه شوند.

👈 برای آشنایی با دیگر ابزارهای رسم شمای دیتابیس به مقاله‌ی 9 نرم‌افزار برتر برای طراحی دیتابیس در سکان آکادمی مراجعه کنید.

۳. مستند Source Code

هدف این مستند نوشتن کامنت و توضیحات بیش‌تر در کنار کد اصلی است تا بتوانید اهداف کد را به صورت واضح‌تر بیان کرده، نگهداری کد و تعامل بین اعضای تیم را بهبود ببخشید. یکی از انواع معروف مستندسازی سورس کد، مستندسازی درون کد (in-code documentation) است. در این مستندسازی، مستندات درون بلوک‌های کامنت و با استفاده از annotation های خاص نوشته می‌شوند. این کار به مستندات یک قالب مشخص و منظم می‌دهد و خوانایی کد را نیز بالا می‌برد. برخی از ابزارهای این نوع مستندسازی در ادامه معرفی شده‌اند.

1.3. ابزار PHP-doc

این ابزار یک روش قدرتمند در php برای نوشتن کامنت و توضیحات با فرمت خاص در کنار کدها است که توسط برخی از IDE ها نیز پشتیبانی می‌شود. این ابزار می‌تواند مستندات را به صورت اتوماتیک از روی annotationها ایجاد و خروجی آن را در قالب‌های مختلفی نمایش دهد.

کد زیر یک نمونه از مستندسازی متد با استفاده از ابزار phpdoc است که در بلوک کامنت‌گذاری ابتدا توضیحی درباره وظیفه متد داده و سپس با استفاده از annotationهای param@ و return@ ورودی و خروجی متد مشخص شده‌اند، همچنین، throw@ خطای متد و حالتی که باعث بروز خطا شده‌است را نشان می‌دهد.

<?php
/**
 * Calculates sum of squares of an array
 *
 * Loops over each element in the array, squares it, and adds it to
 * total. Returns total.
 *
 * This function can also be implemented using array_reduce();
 *
 * @param array $arr
 * @return int
 * @throws Exception If element in array is not an integer
 */
function sumOfSquares($arr) {
    $total = 0;
    foreach ($arr as $val) {
        if (!is_int($val)) {
            throw new Exception("Element is not an integer!");
        }
        $total += $val * $val;
    }
    return $total;
}

2.3. ابزار  JSDoc 

از این ابزار برای مستندسازی کد در زبان javascript استفاده می‌شود و مانند ابزار php-doc امکان کامنت‌گذاری برای کد در بلوک‌های کامنت‌نویسی با استفاده از annotationهای خاص را فراهم می‌کند. این ابزار امکان کامنت‌نویسی  برای ساختار‌های پیچیده مانند کلاس‌ها، ماژول‌ها و namespaceها را نیز فراهم می‌کند.

3.3. ابزار  Sphinx

این ابزار ابتدا برای مستندسازی در پایتون ارائه شد اما در حال حاضر از بسیاری از زبان‌ها پشتیبانی می‌کند. تفاوت این ابزار با دو ابزار قبلی در این است که از فرمت‌های خروجی بیشتری پشتیبانی می‌کند. Sphinx امکان رسم جدول و دیاگرام در مستندات را فراهم می‌کند و امکانات بیشتری برای مستندسازی در اختیار توسعه‌دهنگان قرار می‌دهد، برای مثال همانطور که قبلا گفته‌شد با استفاده از annotationهای ابزار mermaid می‌توان در مستندات تهیه شده توسط این ابزار، دیاگرام رسم کرد.

4. مستند API

مستند apiها یک مستند مهم برای ارتباط و درک بهتر توسعه‌دهندگان با apiهای سیستم است و قابلیت نگهداری، تست و توسعه apiها را افزایش می‌دهد. استفاده تمامی توسعه‌دهندگان از یک مستند مشترک باعث تعامل بهتر بین توسعه‌دهندگان، به خصوص توسعه‌دهندگان فرانت‌اند و بک‌اند می‌گردد و احتمال خطا در درک عملکرد apiها را کاهش می‌دهد.
در این مستند، معمولا ورودی‌ها، خروجی‌ها و نمونه‌هایی از apiهای سیستم مستند می‌شوند که در ادامه به بررسی برخی از ابزار‌های پرکاربرد در تهیه مستند apiها می‌پردازیم.

1.4. ابزار Swagger

مجموعه ابزار Swagger، امکاناتی برای طراحی، مستندسازی و تست apiها فراهم می‌کنند. این مجموعه ابزار، از یک استاندارد با نام OpenAPI برای مستندسازی apiها استفاده می‌کنند. این استاندارد یک فرمت مشخص برای تعریف endpointها، ریکوئست‌ها و ریسپانس‌ها تعریف می‌کند و آن‌ها در قالب یک فایل json یا YAML در می‌آورد. 

نوشتن مستندات api با این استاندارد به صورت دستی می‌تواند زمان‌بر و پیچیده باشد؛ به همین دلیل برای زبان‌های برنامه‌نویسی مختلف، پکیج‌ها و ابزارهایی توسعه یافته‌اند که این فرآیند را خودکار می‌کنند (برای مثال darkaonline/l5-swagger یک پکیج در لاراول برای تولید این مستند است) . 

در این روش، توسعه‌دهندگان با استفاده از annotation یا کامنت‌های مخصوص در کد منبع، apiهای پروژه را مستندسازی می‌کنند و سپس این پکیج‌ها، بر اساس کامنت‌های نوشته‌شده، فایل‌های json یا YAML توصیف‌کننده apiها را مطابق با استاندارد OpenAPI به صورت خودکار تولید می‌کنند.

ابزار swagger ui یکی از ابزار‌های مجموعه ابزار swagger است که با استفاده از فایل json یا YAML توصیف‌کننده apiها، یک ui برای توصیف و تست apiها در مرورگر ایجاد می‌کند.

/**
 * @SWG\Get(
 *   path="/users",
 *   summary="Get a list of users",
 *   tags={"Users"},
 *   @SWG\Response(response=200, description="Successful operation"),
 *   @SWG\Response(response=400, description="Invalid request")
 * )
 */
public function index()
{
    // Your API logic here
}

برخی از پکیج‌ها، مانند G4T Swagger Auto-Generate در لاراول، این امکان را دارند که به صورت خودکار فایل json یا YAML را از روی apiها تولید کنند و دیگر نیازی به مستندسازی توسط توسعه‌دهنده نباشد، اما این پکیج‌ها قابلیت customization پایینی دارند و نمی‌توان آن‌ها را برای اهداف خاص شخصی‌سازی کرد.

مجموعه ابزار Swagger به دلیل تعامل بالا با هوش مصنوعی می‌توانند در مستندسازی به توسعه‌دهندگان بسیار کمک کنند و کارهایی مانند اضافه کردن توضیحات برای فیلدها یا نوشتن مثال در زبان‌های مختلف را به صورت خودکار انجام دهند.

2.4. ابزار Postman

پستمن یکی دیگر از ابزارهای تست و مستندسازی api های سیستم است که دارای تمپلیت‌های مختلف برای طراحی و تست apiها است. با استفاده از تمپلیت داکیومنت این ابزار می‌توان برای apiهای مختلف توضیحات کاملی از ورودی‌ها و خروجی‌ها نوشت و با زبان‌های مختلف برای آن مثال زد. استفاده از پستمن برای توسعه‌دهنگان بسیار آسان است در حالی که کار با swagger نیاز به مطالعه و دانش دارد.

۵. مستند تست نرم افزار

مستند تست‌ها یکی از مستندات مهم در حوزه نرم‌افزار است که نقش مهمی در مدیریت بهتر تست‌ها دارد. این مستند کمک می‌کند تا تمام سناریو‌های موجود برای تست را پیدا کنیم و باعث می‌شود همه توسعه دهندگان تیم یک نگاه مشترک داشته باشند.

یک مفهوم مهم در مستندسازی تست‌ها مفهوم Code Coverage است. این مفهوم نشان می‌دهد که کدهای نوشته شده تا چه میزان توسط تست‌ها پوشش داده شده‌اند. برخی از انواع Code Coverage عبارتند از:

• Line Coverage: میزان پوشش خطوط کد توسط تست‌ها را ارزیابی می‌کند.
• Function Coverage : میزان پوشش متدهای مختلف کد توسط تست‌ها را ارزیابی می‌کند.
• Branch Coverage : میزان پوشش شاخه‌های مختلف یک تصمیم توسط تست‌ها را ارزیابی می‌کند.

ابزارهای مختلفی در زبان‌های برنامه‌نویسی مختلف وجود دارند که میزان پوشش‌دهی کد با تست‌ها را نشان می‌دهند. این ابزار‌ها در قالب یک گزارش برای فایل‌های مختلف میزان پوشش‌دهی کد با تست‌ها را نشان می‌دهند. در ادامه به معرفی برخی از این ابزار‌ها در زبان‌های برنامه نویسی مختلف می‌پردازیم.

۱.۵. کتابخانه JaCoCo 

این کتابخانه برای بررسی Code Coverage در برنامه‌های جاوا طراحی شده‌است که انواع مختلف coverage مانند پوشش‌دهی خط، تابع و شاخه را برای کد‌های زبان جاوا را نشان می‌دهد.

۲.۵. اکستنشن Xdebug 

Xdebug یک اکستنشن در php است که امکان debug و تست کدهای زبان php را فراهم می‌کند. یکی از ویژگی‌های این extension بررسی Code Coverage است که تعداد خط‌های پوشش داده‌شده کد، توسط تست‌ها را اندازه‌گیری می‌کند.

روش‌های مختلفی برای راه‌اندازی Xdebug در php وجود دارد، برای مثال می‌توان تنظیمات آن را در فایل php.ini فعال کرد یا آن را با استفاده از داکر نصب و کانفیگ کرد. این ابزار به طور کلی نشان می‌دهد تست‌ها تا چند درصد از کد‌ها را پوشش داده‌اند. همچنین یک داشبورد در قالب فایل HTML نیز به عنوان گزارش تهیه می‌کند که نشان می‌دهد در هر فایل انواع پوشش‌دهی‌ها تا چه میزان برآورده شده‌اند.

۶. مدیریت و نگهداری مستندات

علاوه بر مستندسازی و تهیه مستندات نرم افزار یک مسئله مهم دیگر، نگهداری مستندات است به طوری که در یک محیط یکپارچه و در دسترس برای تمامی توسعه‌دهندگان قرار گیرند. یک روش پرکاربرد، نگهداری مستندات در یک ریپازیتوری گیت است که با پشتیبانی از زبان‌های Markdown امکان تهیه و نگهداری انواع مستندات را فراهم می‌کند.

علاوه بر ریپازیتوری گیت، ابزار‌های دیگری نیز هستند که امکان نگهداری مستندات در قالب یک سایت را فراهم می‌کنند. از جمله مزیت‌های این ابزار، ارائه یک محیط کاربر پسند و در دسترس برای تمامی کاربران است. در ادامه به بررسی برخی از این ابزار می‌پردازیم:

۱.۶. ابزار  GitBook 

این ابزار یک محیط کاربرپسند و قابل اشتراک برای نمایش و ویرایش مستندات فنی و مستندات استفاده یک سیستم ارائه می‌دهد، به طوری که چندین کاربر می‌توانند به طور هم‌زمان از آن استفاده کنند.
مزیت اصلی این ابزار امکان سینک شدن دو طرفه آن با ریپازیتوری‌های گیت و تبدیل فایل‌های زبان Mardown به مستندات زیبا و کاربرپسند است. اتصال دو طرفه GitBook و ریپازیتوری گیت این امکان را فراهم می‌کند تا تغییرات اعمال شده در GitBook به صورت خودکار در قالب کامیت در ریپازیتوری نیز اعمال شوند این ابزار امکان ورژن‌بندی مستندات متناسب با ورژن‌های پروژه را نیز فراهم‌ می‌کند.

۲.۶. ابزار  MkDocs 

MkDocs یک محیط سبک برای نمایش مستندات در قالب یک سایت فراهم می‌کند. برای راه‌اندازی این ابزار نیاز به نصب پایتون و package manager آن (pip) بر روی سیستم خود داریم. این ابزار از یک فایل YAML برای کانفیگ مستندات و یک فولدر حاوی مستندات برای ایجاد محیط ui استفاده می‌کند.

زبان مستندنویسی مورد استفاده در این ابزار نیز زبان Markdown است و از  تمپلیت‌های متنوعی برای نمایش مستندات پشتیبانی می‌کند.

۳.۶. ابزار  Docusauru 

این ابزار یک سایت ساده و کاربردی تک صفحه‌ای در کوتاه‌ترین زمان برای نمایش مستندات ایجاد می‌کند. برای مثال algolia یکی از تمپلیت‌های این ابزار است که با استفاده از یک موتور جست‌وجو مشکل قابلیت جست‌وجو در میان مستندات پروژه را برطرف کرده‌است.
Docusauru برای تهیه مستندات از زبان Markdown و برای ظاهر سایت از React استفاده می‌کند. Docusauru امکان شخصی سازی و توسعه بالایی دارد، برای مثال می‌توان قابلیت ورژن‌بندی و سرچ بین مستندات برای آن تعریف کرد و کامپوننت‌ها و صفحات آن را توسعه داد.