در این مطلب به چند مورد از انواع مستنداتی که بنظرم باید برای یک پروژه Back-end بنویسم اشاره کردم.
۱. مستندات مخصوص برنامه نویس Front-end:
این مستندات برای شرح نحوه کار با interface پروژه استفاده میشه. از اونجایی که در حال حاضر تمام فریمورک های مدرن جاوااسکریپت با استفاده از اِی پی آی با سرور ارتباط میکنن،در نتیجه باید لیست کاملی از متد ها و ورودی خروجی هارو در اختیار برنامهه نویس فرانت اند قرار بدید. البته عملا باید قبل از انجام پروژه این مستندات با هماهنگی اون شخص نوشته بشه.
یکی از بهترین مثال های این مورد، مستنداتیه که تیم تلگرام در بخش Available methods برای Telegram bot api نوشتند.
۲. مخصوص برنامه نویس Back-end(همکار) و مدیر فنی
این مستندات برای مشارکت کننده ها(contributors) نوشته میشن، کسانی که قصد دارند از عملکرد فنی نرم افزار با جزپیات مطلع بشند و در توسعه یا پشتیبانی پروژه همکاری کنند.
۳. مستندات داخل پروژه (کامنت نویسی)
این مستندات همزمان با کد نویسی نوشته میشند و قراره که ذهنیت برنامه نویس راجع به کدی که مینوسه رو منتقل کنند. این یکی از سخت ترین کار ها برای بعضی برنامه نویس هاست.
به عنوان مثال باید برای تمام فانکشن های نوشته شده کامنت هایی بزارید که دقیقا توضیح بدند این فانکشن چه کاری انجام مید،کجا استفاده میشه، ممکنه چه خطا هایی داخلش رخ بدند، ورودی و خروجی هاش چیا هستند و ... همچنین برای کلاس ها یا هر چیز دیگری باید این کار انجام بشه.
باید اطلاعاتی که در ذهن دارید رو بنویسید تا بقیه برنامه نویس ها دقیقا چیزی که شما از یک قطعه کد میدونید رو بدونند و نیاز به خوانش خود کد نداشته باشند.
بعضی افراد معتقدند که خود کد بهترین سنده. دلایل اشتباه بودن این باور اینه که 1. خوانش کد خیلی بیشتر از خوانش مستندات زمان میبره(مخصوصا در قسمت های پیچیده) و 2. کسی که در حال مطالعست ممکنه دانش فنی کافی برای درک اون قسمت از کد رو نداشته باشه. ولی با مطالعه کامنت ها متوجه عملکرد کد ها میشه.
۴. فایل Readme برای پروژه های متن باز
نهایتا در یک پروژه نیاز دارید که به همه ی مستندات و منابع در یک فایل Readme لینک بدید تا هر کسی با خوانش این فایل بتونه کارش رو با این پروژه شروع کنه.
در این فایل باید توضیح مختصر غیر فنی و فنی در باره پروژه بدید. وابستگی هارو بنویسید. به مستندات لینک بدید. راه های ارتباطی رو بگید. ورژن های اصلی رو لیست کنید و به تغیراتشون لینک بدید. و هر مورد مهم دیگه ای.
امیدوارم این توضیحات مفید بوده باشند.
خوشحال میشم اگر نظرتون رو بنویسید.
