همیشه یکی از بحث های جنجالی و یا نا جنجالی در زمینه توسعه نرم افزار بحث مستند سازی یا Documentation بوده است . شرکت های توسعه نرم افزار در ایران جزو عجایب الخلقه های هستی به شمار می آیند  چراکه تنها در این بحث مسستند سازی کارهای محیر العقولی انجام می دهند ; یا اصلا (و ابدا) مستند سازی نمی کنند (من عاشق این اخلاقشون هستم ) و یا آنقدر مستند سازی می کنند که برای کارهای دیگر وقت ندارند . اما در این پست قصد دارم با هم بررسی بکنیم که در Agile برای مستند سازی چه چیزی پیشنهاد شده است .

در مستند سازی Agile مانند همه دیگر عمل های چابک ,  شما به اعتدال در اعمال دعوت شده اید . شعار تیم های توسعه در تهیه مستندات پروژه : ” فقط به اندازه کافی و صحیح مستند سازی خواهیم کرد “. این شعار در عمل بسیار سخت می باشد (مانند دیگر شعارهایی که می دهیم و فقط شعار می دهیم ) زیرا ما دماسنجی نداریم که درجه کافی بودن مستندسازی را مشخص نماید . تنها راهی که می توان معیاری برای کافی بودن مستندسازی ارائه کرد ,  مشخص کردن اهداف مستند سازی می باشد .

بعضا این دوستان خارجی یک صحبت هایی دارند که در حد کتاب های مقدس (الهی ) برای ما توسعه گران نرم افزار ارزشمند می باشد. یکی از این صحبت ها که نقل محفل ما هم می باشد عبارتست از :

Tell me how you will measure me and I ‘ll tell you how I will behave

این جمله اهمیت تبیین هدف را مشخص می کند . در بحث مستند سازی خودمان ,  عرض شد که برای تعیین معیار کافی بودن مستند سازی نیاز به تبیین هدف می باشد . به عبارت ساده تر یعنی کسی که می خواهد مستند سازی کند می فرماید : ” به من بگو چرا باید مستند سازی بکنیم تا من به شما بگویم که چقدر مستند سازی بکنیم کافی است ” .

نوبت این رسیده که دوستان را در زمینه هدف سازی برای مستند سازی راهنمایی کنیم . هدف هایی زیادی در هر پروژه و یا در هر شرکت می تواند به عنوان هدف مستند سازی تببین شود مثلا شرکتی می خواهد برای محصول خود User Manual تهیه نماید که در بحث مستند سازی  باید حدکافی این مقوله رعایت شود . ولی اصلی ترین و در واقع مهم ترین علت و هدف از مستند سازی در ایران نگه داری (Maintenance) سیستم می باشد .اما چه دلیلی باعث می شود که برای نگه داری سیستم نیاز به مستندات باشد ؟ دو عامل باعث می شود که نیاز به مستندات داشته باشیم : 1- نیروی کار فراموش کار است (برنامه نویس یک هفته بعد کاملا همه چیز را فراموش خواهد کرد و انگار اصلا او این کدها را ننوشته است) 2- وظیفه نگه داری سیستم توسط تیمی به جز تیم توسعه آن سیستم انجام خواهد شد.

این دو عامل و هدف بهترین معیار در طول مستند سازی برای ما می توانند باشند . یعنی اگر سوال پیش بیاید که چقدر باید مستند سازی بکنیم : جواب خواهیم داد که تا قدری که بتوان از سیستم نگه داری کرد و اگر سوال پیش بیاید که چگونه (How) باید مستند سازی بکنیم : جواب این خواهد بود که طوری مستند سازی باید کنیم که اگر فردا روز خواستیم و یا خواستند تغییری در این قسمت از برنامه بدهیم یا بدهند ,  بتوانیم و یا بتوانند با خواندن مستندات ما به کاری که در اینجا انجام می گیرد پی ببریم و یا ببرند و تغییرات را به راحتی اعمال نماییم و یا نمایند .

سوالات متدوالی در زمینه مستند سازی مطرح می شود که در زیر تعدادی آن ها مطرح می شود :

• چه چیزهایی را باید مستند کنم و آیا اسم توابع را هم باید مستند کنم و در مورد ریزه کاری ها چطور ؟

جواب این سوال در بالا داده شد : طوری مستند سازی باید کنیم که اگر فردا روز خواستیم و یا خواستند تغییری در این قسمت از برنامه بدهیم یا بدهند ,  بتوانیم و یا بتوانند با خواندن مستندات ما به کاری که در اینجا انجام می گیرد پی ببریم و یا ببرند و تغییرات را به راحتی اعمال نماییم و یا نمایند . ولی مسئله اصلی این است که مستندات به گونه ای باید باشد که خودمان و یا دیگران با خواندن مستندات به کلیت کار پی ببرند و لاز م نیست که ریز مسائل را بیان کنیم (البته مسائل ریزی که مهمی نیستند) مثلا در مستندات لازم نیست که بیان شود دو تا متغیر int تعریف کردم سه تا Dataset و … . به عبارت ساده هر موردی که فکر می کنید در دفعات بعدی برای فهمیدن آن بخش از سیستم لازم باشد را مستند سازی کنید .

• آیا Comment نویسی برای کد ها لازم است ؟

به نظر بنده کامنت نویسی نیاز نیست اگر کدها تمیز باشند والبته  اگر کدها Refactor شده باشد و در کل اگر متد TDD باشد به هیچ وجه نیازی به کامنت نویسی نمی باشد و در کل کار جالبی نیست.

یاشیاسیز