چرا نرم افزار را مستند می‌کنیم؟ شیوه بهینه و مدرن مستندسازی فنی چیست؟

من فرض میگیرم که انسان تنبل است و فراموش کار. بنابراین دغدغه من این است که چگونه با درنظر گرفتن این شرایط، محصولات نرم افزاری را مستند کنیم.
به تجربه خودم و دیگران فهمیده ام که مستندات متنی طولانی به هیچ کار نخواهد آمد. بروز هم نخواهد شد. خب حالا با این وضعیت چکار کنیم؟

من در این حالت ترجیح میدهم که به اصل سوال رجوع کنم: ” اساسا چرا به مستند فنی نیاز داریم؟ “
برای من سه چیز مهم است:
۱- مدیریت دانش اعضای داخل تیم و انتقال دانش به همه اعضا
۲- آموزش سیستم به نیروی جدید الورود شرکت
۳- امکان نگهداری بهینه سیستم و افزودن امکانات به آن

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

اما اگر شما هم موارد بالا برایتان اهمیت دارد، پس باید شیوه صحیح مدیریت دانش و تهیه مستندات فنی را انجام دهید.
برای رسیدن به این هدف باید مواردی را در حین توسعه سیستم در نظر بگیریم.

مختصر و مفید: راه حل مبنایی و قطعی نوشتن ” کد تمیز ” و ” استاندارد ” است.
هزاران ساعت آموزش، کتاب و مقاله در اینترنت برای کد‌نویسی تمیز وجود دارد. باید این استانداردها را رعایت کنیم. اصول کدنویسی تمیز، solid و سایر اصول را جدی بگیریم. مثلاً به جای اعداد جادویی از enum استفاده کنیم.

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

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

از تست های برنامه به عنوان یک مستند خوب هم می شود استفاده کرد. تست هایی که خوب نامگذاری شده اند و هدف یک کسب و کار و فرایند را شرح میدهند، منبع بسیار خوبی برای یادآوری کدهای قدیمی هستند. همچنین اعضای جدید هم راحت تر می توانند منطق فرایندها را درک کنند.

مساله مهم دیگر کدنوشتن دونفره pair programming یا چندنفره mob programing است. این مدل کدنوشتن کمک میکند که سلیقه های تیم مشترک شود و سطح دانش افراد هم تراز شود. در نهایت کدها یکدست شده و برای اعضای تیم خواناتر خواهد شد، اختلاف سلیقه کمرنگ تر شده و کیفیت کدها افزایش خواهد یافت.

امروزه framework و چهارچوب های بسیاری برای انواع زبان های برنامه نویسی وجود دارد. انتخاب یک فریم ورک خوب میتواند کمک زیادی به کیفیت کد و کم شدن نیاز مستندسازی داشته باشد. مثلا در زبان js انتخاب چهارچوبی مثل nestjs برای نوشتن api باعث می شود که کد نهایی ساختار منظم و قابل قبولی داشته و یکدست باشد. مستندات خوب nestjs هم کمک میکند که افراد جدید نیازی به مستندات داخل شرکت نداشته باشند و از مستندات باکیفیت فریم ورک بهره مند شوند.

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

اکثر برنامه های مدرن امروزی از یک api و یک web client  یا mobile client تشکیل شده است. در این شرایط ارتباط بین دوتیم نیاز به مستندات و هماهنگی زیادی دارد. استاندارد swagger یا openApi باعث می شود که مستندات api به طور خودکار تولید شود. تیم client از آخرین تغییرات آگاه شود و خطای انسانی در مستندسازی ایجاد نشود.

اما میتوان با استاندارد swagger کارهای دیگری هم کرد. چون swagger یک فرمت توصیفی است و مدل api را به صورت ماشینی در قالب json توصیف میکند، ابزارهایی وجود دارند که خروجی swagger را تبدیل به کد مثلا ts می کنند.

این کار باعث میشود که حجم زیادی از کد به صورت خودکار تولید شود. در نتیجه زمان پروژه کوتاه تر می شود. خطای ارتباط با api کم می شود. نیازی به مستندسازی برای هماهنگی هم وجود ندارد. در صورت تغییر هم می توان با یک دستور و ساخت دوباره مدل از تغییرات آگاه شد.

اگر موارد بالا را رعایت کرده باشیم، در نهایت چیزی که نیاز به مستندات دارد کلیات ساختاری است. برای این موارد در قالب ویدئوهای کوتاه یا تصاویر که حین کار تهیه می شود می توان مستندات را کامل کرد. مثلا دلایل انتخاب معماری، توضیح ساختار پروژه، دلیل استفاده از واسط پیام message broker و موضوعاتی از این قبیل.

حالا یک تست عملیاتی کنید. نفر جدید که وارد سازمان می شود را زیرنظر داشته باشید. اگر براحتی کد را فهمید و اولین کارش رو در زمان کوتاه انجام داد اوضاع خوب است. اما اگر زمان غیرمعقولی طول کشید دوحالت وجود دارد: یا مستندات خوب نیست، یا فرد مناسبی را استخدام نکرده اید.