چرا باید از مستندسازی در کد نویسی خود استفاده کنیم؟
زمانی که صحبت از توسعه نرم افزار می شود با اصطلاحاتی مانند Solid، DRY، KISS که جزئی از اصول توسعه نرم افزار در الگوهای طراحی هستند، روبه‌رو می شوید؛ اما زمانی که سخن از مستندسازی و بررسی کدها می شود مطالب زیادی در مورد آن پیدا نمی کنید. اما واقعاً چرا این گونه است؟
مستندسازی باید به اندازه سایر جنبه های توسعه نرم افزار برای برنامه نویسان مهم باشد. در این مقاله به این بحث خواهیم پرداخت که چرا مستند سازی به شما برای تبدیل شدن به یک برنامه نویس عالی کمک می‌کند.
هیچ‌کس برای انجام این کار وقت ندارد
یکی از دلایلی که باعث می شود کدها بدون مستندسازی باشند، مسئله زمان است. زمانی که باید در مدت اندکی ویژگی هایی را به برنامه اضافه کنیم، به ندرت برای مستندسازی کدها وقت کافی داریم. در روند توسعه نرم افزار علاوه بر طراحی و نوشتن کد باید بر روی مسائل دیگر مانند بازبینی کدها، آزمون های خودکارسازی و اضافه کردن تست های واحد تمرکز کنیم.
کم اهمیت ترین و کوچک ترین جزییات می تواند مهم ترین تغییرات را در آینده به دنبال داشته باشد
مهم نیست که چه چیزی را توسعه می دهید، در آينده ممکن است کدها را با فرد دیگری مورد بازبینی قرار دهید. زمانی که آن روز فرا رسد، به احتمال زیاد از کدهایی که خودتان نوشته اید تعجب می کنید و آن ها را به درستی به یاد نخواهید آورد. همچنین ممکن است با کدهایی مواجه شوید که کاربرد خاص خود را دارند و برایتان واضح نباشند. برای حل این مشکل می توان از مستندسازی کدها استفاده کرد. این کار می تواند باعث صرفه‌جویی در وقت شما گردد و همچنین افراد دیگر بهتر می توانند کدهای شما را درک کنند. از این گذشته به‌عنوان یک برنامه نویس زمانی که قصد دارید مطلب جدیدی یاد بگیرید چه کاری انجام می دهید؟ بله قطعاً به سراغ مستندات خواهید رفت.
کد خوب نیازی به مستندسازی ندارد
کدهایی که از نظر نوشتاری و فهم خوب باشند، نیازی به مستندسازی ندارد. این موضوع ممکن است درست باشد، اما نباید مستندسازی کدها را نادیده بگیریم. در زیر می توانید دلایل این امر را متوجه شوید:
۱. همه ما با کدهای خوانا آشنا هستیم؛ اما در برخی مواقع ممکن است با نگاه به یک تکه کد متوجه نشویم که آن قطعه کد با بخش‌های دیگر در ارتباط است. به همین دلیل آن قسمت باید مستندسازی شود.
۲. هر سرویسی که ایجاد می‌کنید، ممکن است شامل یک یا چند API منحصر به فرد شود. اینکه چگونه باید از این API استفاده کنیم، نیاز به مستندسازی دارد به طوری که بتوان خارج از کدها آن را مطالعه کرد.
۳. همکاران شما که در بخش های مختلف شرکت فعالیت می کنند، ممکن است کدهای شما را بخوانند. بنابراین برای درک کدها باید به اسناد و توضیحات آن رجوع کنند.
۴. مستندسازی کدها باعث می شود تا شما دیدی متفاوت به کدهای نوشته شده داشته باشید. اینکه توضیح دهید هر خط کد چه‌کاری را انجام می دهد، باعث می شود که اعتبار آن را دوباره ارزیابی کنید و در صورت برآورده نشدن انتظاراتتان در کدها تغییر ایجاد کنید.
چگونه مستندسازی خوب بنویسیم؟
نوشتن مستندسازی خوب درست همانند کد نویسی خوب است. مستندسازی باید کوتاه، ساده، آسان و برای افراد قابل فهم باشد. در زیر چند راهنمایی برای نوشتن مستندسازی وجود دارد:
۱. مشخص کنید که هدف اسناد برای چه مخاطبانی است. آیا مستندسازی تنها برای برنامه نویسان نوشته شده است یا افراد بیشتری وجود دارند. دانستن این موضوع باعث صرفه‌جویی در وقت شما خواهد شد. با در نظر گرفتن مخاطب خاص می‌دانید که مباحث را باید به چه شکل توضیح دهید.
۲. یک یادداشت کوتاه اما توصیفی بنویسید و نکات اصلی آنچه را که ساخته‌اید، توضیح دهید. این کار به خوانندگان کمک می‌کند تا هدف این ویژگی را بفهمند و نیازهای خود را مطابق با آن بدانند.
۳. چشم‌انداز اصلی خود را در یک لیست توصیف کنید و اطمینان حاصل کنید که وابستگی‌های موجود بین ویژگی‌های پروژه به‌خوبی مشخص شود.
۴. مطمئن شوید که از علامت زمانی در کدها استفاده می‌کنید تا صحت کد برای خوانندگان روشن شود. همچنین اگر از کتابخانه‌ای خاصی استفاده می‌کنید، حتماً آن‌ها را در مستندسازی خود ذکر کنید.
۵. هرکدام از پیاده‌سازی‌ها و جزییات کد را به طور کامل شرح دهید و نتایج موردنظر را نشان دهید.
نمونه
برای درک بیشتر به چند نمونه از مستندسازی اشاره می کنیم:
در مستندسازی سایت MDN به وضوح می توانید مشاهده کنید که هر صفحه با توضیحات مختصری شرح داده شده است. پس از آن موارد و روش های مورد استفاده را به تفصیل توضیح می دهد و در نهایت نشان می دهد با کدام مرورگرها با ویژگی های آن سازگار هستند و لینک هایی برای مطالب مرتبط ایجاد می کند.
در مستندسازی سایت Stripe هر مطلب شامل یک قطعه کد به زبان های مختلف است.
در عکس بالا می‌توانید مستندسازی قوی سایت جنگو را مشاهده کنید. مهم نیست که در چه سطحی از کد نویسی قرار دارید، شما با استفاده از آموزش‌ها این سایت می توانید آن را به خوبی بیاموزید. تمام مباحث در این سایت به خوبی توضیح داده شده است و همراه آن قطعه کدهایی قرار داده شده که نشان می دهد چه کار باید انجام گردد.
اکنون شما اهمیت مستندسازی در برنامه نویسی را درک کرده اید. اگر ایده هایی در مورد مستند سازی کدها دارید می توانید در نظرات آن را با ما به اشتراک بگذارید.
منبع برگرفته از:
حالا بهت پینهاد می کنم که وبلاگ چه زمانی لازم است که از زبان های قدیمی برنامه نویسی استفاده کنیم؟ را در ادامه این مطلب بخونی.
اگر علاقه مند به شرکت در دوره‌های برنامه نویسی هستین:
میتونین در بوت‌کمپ‌ها
کنین، و وارد بازارکار بشین!