سیستمهای مختلف، توصیه های متفاوتی برای نوشتن مستندات دارن. سیستم های تولید نرم افزار قدیمی ما رو به نوشتن مستندات از نقطه آغازین پروژه ترغیب میکنن و در طول چرخه توسعه نرم افزار از ما میخوان تا مستندات رو با خود نرم افزار بطور موازی پیش برده و به روز نگه داریم. به همین دلیل، وقتی پروژه ای شروع میشه، تلاش بسیار زیادی برای نوشتن مستندات صورت میگیره و این تلاش با گذشت زمان از اجرای پروژه، سرعت کمتری بخودش میگیره. اینکه این مستندات رو برنامه نویس تولید کنه، یا تیمی کاملا جداگانه، باز هم بستگی به سیستمی داره که در اون مستندات رو تولید می کنید.
بطور مثال، در چرخه تولید نرم افزار (SDLC) به روش Lean (یا Agile)، برنامه نویس عملیات مستند سازی رو باید به تعویق بندازه، چون هنوز هیچ اطلاعاتی Fix نشده و سیستم مدام در حال تغییره. مهیا کردن مستندات بر اساس روش Agile باعث کاهش هزینه ها میشه چون دیگه برنامه نویس وقتش رو صرف نوشتن مستنداتی که در آینده ای بدلیل تغییرات در برنامه، تغییر خواهند کرد، نمیکنه. ثانیا خطر تغییر "مستندات طراحی" بسیار کاهش پیدا میکنه. شما ممکنه یک طرح رو بارها تغییر بدید چون ایده هاتون به مرور زمان تغییر میکنه. وقتی این اتفاق بیفته، خطر دوباره کاری نوشتن مستندات از بین میره.
به همین دلیل، بهترین زمان نوشتن مستندات هنگامی هستش که پروژه پایان پذیرفته و شما کاملا از کارکرد سیستمی که در دست دارید، مطلع هستید. طبیعتا تهیه مستندات در انتهای پروژه معایبی نیز در پی داره:
- ممکنه شما دلائل برخی از کارها و انتخابهایی که کرده بودید رو فراموش کرده باشید و هرگز موضوع مربوطه رو به یاد نیارید
- ممکنه دیگه دستتون به افراد تیم خودتون نرسه (به این دلیل که اونها روی پروژه دیگه ای متمرکز شده اند، شرکت رو ترک کرده اند و ...)
- ممکنه دیگه بودجه ای برای این کار در انتهای پروژه برای شما باقی نمونده باشه
- و مهمتر از همه، دیگه حوصله مستند سازی رو نداشته باشید
بنابراین بهتره توازنی بین زمان نوشتن مستندات و انجام پروژه برقرار کنیم تا به مشکلات فوق برنخوریم.
آقای عسگری، گمان میکنم بهتره تا بحث مستند سازی رو در اینجا تموم کنیم، چون حقیقتا این مساله داره به خارج از حوزه ای که در اون صحبت می کردیم منتقل میشه. تنها نکته ای که در بحث مستند سازی باقی مونده، و با اجازه شما و آقای مداح میخوام اونو مطرح کنم، Extract کردن XML Document ها از درون کد و تولید فایل مستندات هستش. برای این منظور نرم افزارهای زیادی وجود داره که یکی از اونها NDoc هستش. متاسفانه این پروژه Open Source بالغ بر 5 سال هستش که دست نخورده رها شده و در نتیجه دیگه از اون استفاده نمیشه.
در عوض، توسعه گران دسترسی به ابزاری معادل NDoc دارن، البته این بار این ابزار توسط مایکروسافت پشتیبانی میشه. نام این ابزار Sandcastle هستش. خوشبختانه این ابزار در ماه جاری میلادی (دقیقا 6 روز پیش و پس از دو سال از آخرین نسخه) به روز شده و از این آدرس در دسترسه.
Sandcastle از .NET 4.0 پشتیبانی میکنه و بالغ بر 100 خطایی که در نسخه آخر اون بود، در نسخه جدید رفع شده.
برای شروع، ابتدا Sandcastle رو دریافت و نصب کنید. پس از اتمام عملیات نصب، Visual Studio رو باز کرده و پروژه مورد نظرتون رو باز کنید. سپس روی نام پروژه Right-Click کرده و گزینه Properties رو انتخاب کنید. سمت چپ، آیتم Build رو انتخاب کرده و سمت راست، گزینه XML documentation file رو انتخاب کنید. با این تغییر، Comment هایی که در برنامه نوشته بودیم، تحت قالب یک XML در خروجی قرار میگیره (پس از اینکه پروژه رو مجددا Compile کردید).
اکنون به شاخه ای که Sandcastle رو نصب کرده اید برید و از شاخه Examples، زیر شاخه Generic رو انتخاب کنید. اونجا فایلی تحت نام SandcastleGui.exe وجود داره. این برنامه اجرا کنید...
نام Assembly مورد نظرتون رو در قسمت Assemblies پنجره باز شده وارد کنید. همینطور، نام فایل XML تولید شده رو (که بصورت پیش فرض در شاخه Debug برنامه قرار میگیره)، در بخش Comments اضافه کنید. در قسمت Options (سمت راست صفحه) نام فایل CHM مورد نظرتون رو انتخاب کنید. فایل CHM مورد نظر با این اسم ذخیره خواهد شد.
اکنون کلید Build رو فشار داده و کمی منتظر بمونید.
در نهایت، وقتی کار این Utility تموم بشه، با پیامی شبیه این مواجه خواهید شد:
Created c:\Program Files\Sandcastle\Examples\App1Doc\vs2005\chm\App1D oc.chm, 107,986 bytes
(من اسم App1Doc رو برای فایل CHM خودم انتخاب کرده بودم). اکنون به مسیر فوق برید و فایل CHM مزبور رو باز کنید. من این کار رو برای کلاس Porsche که در موردش صحبت کردیم انجام دادم و Snapshot ای از اون رو برای مشاهده شما اینجا قرار میدم:
دقت کنید، چون این ابزار 6 روز پیش Update شده و در دسترس عموم قرار گرفته، هنوز Documentation های شسته و رفته ای نداره، بنابراین باید خودتون زمان بذارید و fبا جزییاتش آشنا بشید. تا هنگامی که مستندات این ابزار توسط مایکروسافت به روز نشده، می تونید از این آدرس برای کسب اطلاعات بیشتر استفاده کنید.
در ضمن همونطوریکه شما فرمودید، بحث MVVM در قالب این گفتگو قرار نمیگیره، اگرچه استفاده از الگوهای طراحی همواره به نوشتن کد بهتر و خواناتر، کمک شایانی میکنه. بسیار خوب، آقای عسگری؟
(توضیح اینکه هر چقدر معطل کردم تا پاسخ آقای عسگری رو دیرتر بدم تا بلکه پروژه Sandcastle Help File Builder (بر اساس اعلان قبلی) به روز بشه، این اتفاق نیفتاد و تصمیم گرفتم تا حضار رو بیشتر از این معطل نذارم. این پروژه وقتی به روز بشه، GUI ای مطابق NDoc به شما ارائه میکنه، که دقیق بوده و قابل استفاده هستش. GUI ای که من در فوق به اون اشاره کردم، فقط نمونه ای بود برای نمایش توانایی های Utility مزبور و هرگز جایگزینی برای NDoc محسوب نمیشه. تیم مربوطه مجددا پیش بینی کردن که این ابزار فردا برای Download محیا هستش).
