پرش به مطلب اصلی

الزامات مستندسازی

فهرست مطالب​

فلسفه مستندسازی​

تیم ما معتقد است که مستندسازی جامع برای حفظ یک پایگاه کد پایدار و فرآیند توسعه کارآمد ضروری است. فلسفه مستندسازی ما با این اصول هدایت می‌شود:

  1. مستندسازی به عنوان شهروند درجه یک: مستندسازی به اندازه کد مهم است
  2. برای آینده بنویسید: مستندات را برای اعضای آینده تیم (از جمله خود آینده‌تان) بنویسید
  3. متن مهم است: «چرایی» پشت تصمیمات را توضیح دهید، نه فقط «چه» و «چگونگی» را
  4. به‌روز نگه‌داری کنید: مستندات قدیمی اغلب از نبود مستندات بدتر است
  5. سطح مناسب جزئیات: تعادل بین جامعیت و قابلیت نگهداری را رعایت کنید

انواع مستندات مورد نیاز​

الزامات مستندات کد​

مطابق با استانداردهای کدنویسی جهانی:

  • PHPDoc/JSDoc: تمام متدها و کلاس‌های عمومی باید بلوک‌های مستنداتی داشته باشند
  • منطق پیچیده: توضیحات درون خطی برای کدهای غیربدیهی اضافه کنید
  • ثابت‌ها: هدف و مقادیر معتبر ثابت‌ها را مستند کنید
  • استثناها: زمان و دلیل پرتاب استثناها را مستند کنید
  • وابستگی‌ها: وابستگی‌های خارجی و هدف آن‌ها را مستند کنید

مثال مستندات متد PHP:

/**
 * بازیابی کاربر با استفاده از آدرس ایمیل
 *
 * @param string $email آدرس ایمیل کاربر
 * @return User|null شیء کاربر در صورت یافتن، در غیر این صورت نال
 * @throws InvalidArgumentException اگر فرمت ایمیل نامعتبر باشد
 */
public function getUserByEmail(string $email): ?User
{
    // پیاده‌سازی
}

استانداردهای مستندسازی​

قالب‌بندی​

  • از Markdown برای تمام مستندات استفاده کنید
  • از ساختار سربرگ یکپارچه پیروی کنید
  • از بلوک‌های کد با هایلایت سینتکس مناسب استفاده کنید
  • جداول را برای داده‌های ساختاریافته شامل شوید
  • در صورت لزوم از نمودار استفاده کنید (ترجیحاً Mermaid.js)

سبک نگارش​

  • به زبان واضح و مختصر بنویسید
  • از صیغه معلوم استفاده کنید
  • مشخص و همراه با مثال بنویسید
  • از اصطلاحات تخصصی و اختصارات بدون توضیح خودداری کنید
  • از اصطلاحات یکسان استفاده کنید

سازماندهی مستندات​

  • مستندات مرتبط را گروه‌بندی کنید
  • از نام‌ فایل‌ها و عناوین توصیفی استفاده کنید
  • برای اسناد طولانی فهرست مطالب قرار دهید
  • به مستندات مرتبط لینک دهید
  • از تگ‌ها برای قابلیت جستجو استفاده کنید

ابزارهای مستندسازی​

  • Docusaurus: پایگاه دانش اصلی (همین سایت)
  • PHPDoc/JSDoc: مستندات کد
  • OpenAPI/Swagger: مستندات API
  • Mermaid.js: نمودارهای تعبیه شده در Markdown
  • Confluence: مستندات اضافی پروژه

فرآیند بازبینی مستندات​

مستندات باید به عنوان بخشی از فرآیند بازبینی کد بررسی شوند:

  1. بررسی کامل‌بودن و صحت
  2. تأیید به‌روز بودن مستندات
  3. اطمینان از رعایت استانداردهای مستندسازی
  4. تأیید کارکرد مثال‌های ارائه شده
  5. بررسی وضوح و خوانایی

نگهداری مستندات​

  • با تغییر کد، مستندات را به‌روز کنید
  • مستندات را سه‌ماه یکبار برای دقت بررسی کنید
  • مستندات منسوخ را بایگانی کنید
  • بدهی مستندات را همزمان با بدهی فنی ردیابی کنید
  • برای بخش‌های مختلف، مالک مستندات تعیین کنید

معیارهای مستندات​

این معیارها را برای اطمینان از کیفیت مستندات ردیابی می‌کنیم:

  • پوشش مستندات (درصد کد دارای مستندات)
  • تازگی مستندات (تاریخ آخرین به‌روزرسانی)
  • کامل‌بودن مستندات (بر اساس چک‌لیست)
  • بازخورد کاربران درباره مفید بودن مستندات
  • زمان صرف شده توسط اعضای جدید تیم برای یافتن اطلاعات

یکپارچه‌سازی با فرآیند توسعه​

مستندسازی در فرآیند توسعه ما یکپارچه شده است:

  • به‌روزرسانی‌های مستندات در درخواست‌های ادغام الزامی است
  • خط‌لوله CI/CD پوشش مستندات را بررسی می‌کند
  • مستندسازی بخشی از تعریف تکمیل کار است
  • زمان مستندسازی در برآورد وظایف لحاظ می‌شود
  • کیفیت مستندسازی بخشی از معیارهای بازبینی کد است
آخرین به روز رسانی در تاریخ توسط Behnam Moradi