وقتی وارد دنیای توسعه نرم افزار میشویم، با اصطلاحات بسیاری روبرو خواهیم شد. KISS، DRY، SOLID و... . اما وقتی موضوع به مستندسازی یا کامنت کردن کدهایتان میرسد چنین کلمات دلفریبی را زیاد نمیبینید.
چرا اینگونه است؟
مستندسازی دقیقا باید به اندازه دیگر جنبههای فرایند توسعه برای افراد برنامهنویس مهم باشد.
در این مقاله به شما میگویم که چرا مستندسازی از شما توسعهدهنده و مشارکت کننده بهتری در تیمتان میسازد.
هیچکسی زمان برای انجام این کار را ندارد
یکی از دلایل اصلی که باعث میشود کدها بدون مستندسازی ارائه شوند، زمان است. وقتی که باید در یک مدت زمان کوتاه ویژگی خاصی را به نرم افزار اضافه کنیم، بسیار به کمی پیش میآید که به مستندسازی کدهایمان نیز فکر کنیم.
در یک روند معقول توسعه نرم افزار، معمولا جدای از طراحی و کدنویسی شما باید کارهای دیگری را نیز انجام دهید، بازبینی کردن کدها، خودکارسازی تستها، استفاده از تستهای واحد و... . مستندسازی فرایندی است که در این مرحله از کار بسیار به کمی نام برده میشود.
کمترین جزئیات همواره میتوانند مهمترین تفاوتها را در آینده شکل دهند.
مهم نیست چه چیزی را توسعه میدهید، در آینده مطمئنا شما یا فرد دیگری مجبور خواهید بود که کدها را مطالعه یا بازبینی کنید. وقتی آن روز فرا رسید، به احتمال بسیار زیاد چیزهایی که نوشتهاید و چرایی نوشتن آنها را به درستی به یاد نخواهید آورد.
همچنین با قسمتهایی از کدهایتان برخورد خواهید کرد که در مورد آنها شک دارید، تنها راهحلی که میتواند تمام این مسائل را واضح بکند، مستندسازی است.
تعیین زمان کمی برای نوشتن و توضیح دادن آنچه که نوشتهاید، میتواند مدت زمان بسیار زیادی را در آینده برایتان نجات دهد.
دفعه بعدی که فردی بخواهد چیزی که در کدهایتان اتفاق افتاده است را درک کند، تنها کاری که نیاز به انجام دادن است این است که سراغ مستندسازی و توضیحات شما برود. از آنجایی که نیازی به توضیح دادن آنها به صورت مستقیم ندارید، بنابراین زمان زیادی را از صرف شدن نجات میدهید. همچنین از آنجایی که آنها به شما وابسته نخواهند بود زمان آنها نیز ذخیره میشود.
جدای از تمام اینها، وقتی که شما به عنوان یک توسعهدهنده قصد دارید تا چیزی را در رابطه با کدنویسی یاد بگیرید چه کاری را انجام میدهید؟
به سراغ مستندات میروی!
کدی که خوب نوشته شده باشد نیازی به مستندسازی ندارد
همواره این موضوع را به من میگویند و قضیه را به خوبی میدانم. کدهایی که خوب نوشته شده باشند نیازی به مستندسازی ندارند.
در حالیکه ممکن است چنین موضوعی واقعیت داشته باشد اما این بدان معنا نیست که حتما باید از مستندسازی دوری کنیم. در اینجا میتوانید دلیل آن را مشاهده کنید:
- همه ما با کدهای قدرتمندی آشنا هستیم که یک ویژگی را ارائه میدهند. اما گاهی اوقات یک قسمت از کد به صورت واضح ارتباطش را با دیگر قسمتهای کد نشان نمیدهد. به همین دلیل این موضوع باید توضیح داده شود.
- هر سرویسی که ایجاد میکنید ممکن است شامل یک یا چند API منحصر به فرد شود. شیوه استفاده از این APIها نیازمند نوشتن مستندات میشود. مستنداتی که بتوان آنها را خارج از کدها مطالعه کرد.
- همکاران در یک شرکت بزرگ معمولا در دپارتمانهای مختلفی کار میکنند، به همین دلیل در صورتی که همه آنها توسعهدهنده نباشند ممکن است درک چیزهایی که به صورت کد نوشتهاید برایشان سخت باشد.
- خود حقیقت نیز ممکن است باعث شود که شما نگاهی متفاوت با آنچه که نوشتهاید داشته باشید. توضیح اینکه کدتان چه کاری را انجام میدهد به شما و دیگران این قابلیت را میدهد که تنها منتظر کارهایی باشید که انتظارش را دارید و با چیزهای عجیب و غریب روبرو نشوید.
چگونه مستندات خوبی بنویسیم؟
مستندات خوب مانند یک بلاک خوب کد هستند. کوتاه، ساده و درک پذیری آسان. در زیر میتوانید چند نکته کمکی برای نوشتن مستندات را دنبال کنید:
- جامعه هدف مستندسازی را شناسایی کنید. آیا این مستندات تنها برای توسعهدهندگان نوشته میشود؟ آیا مخاطبین بیشتری را در بر میگیرد؟ درک این موضوع میتواند در زمانتان نقش بسیار مفیدی ایفا کند. با در نظر گرفتن مخاطبانتان حال میدانید که دقیقا به چه شکلی مباحث را توضیح دهید.
- هدف اصلی چیزی که ساختهاید را به صورت کوتاه و در عین حال مفهومی بنویسید. این موضوع به خوانندگان کمک میکند تا هدف هر یک از ویژگیهای نرم افزار را درک کنند و مواردی که خودشان میخواهند را ارزیابی نمایند.
- چشماندازهای آینده را لیست کنید و شرح دهید، مطمئن شوید که به تمام مستقلات و نیازمندیهای مربوط به پروژهتان اشاره میکنید.
- مطمئن شوید که مستندات را براساس نسخههای نرم افزاری مینویسید، به این صورت خوانندگان میتواند اعتبار بیشتری را در مستندسازیتان ببینند. همچنین اگر از کتابخانه معینی استفاده میکنید، مطمئن شوید که آن را نیز در نسخههای مستندسازیتان قرار خواهید داد.
- در رابطه با مثالهای کدنویسی سخاوتمندانه رفتار کنید. در رابطه با پیادهسازی هر کدام از ویژگیها به صورت مفصل شرح دهید و خروجیهای مورد انتظار را نشان دهید.
نمونهها
در ادامه با ارائه چند مثال قصد داریم یک نمونههایی از مستندسازیهای خوبی را به شما نشان دهیم:
در مستندات مربوط به MDN میتوانید ببینید که در هر صفحه به صورت خلاصه وار نوشته و توضیحاتی راجع به هر موضوع قرار گرفته شده است.
بعد از آن شروع به ارائه توضیحات راجع به متدها و حالتهای مختلف دیگری میکند. در نهایت هر صفحه به شما میزان سازگاری ویژگی را با مرورگر به شما میدهد و همچنین لینکهای کمکی مرتبطی را نیز ارائه میکند.
در مستندات Stripe هر موضوعی قطعه کدهایی را شامل میشود که میتوان آن را در زبانهای کدنویسی مختلفی مشاهده نمود.
مستندات جانگو بسیار قدرتمند است. مهم نیست که در چه سطحی از کدنویسی قرار دارید، میتوانید با آموزشهای جانگو همراه باشید.
هرکدام از موضوعات در این مستندات به خوبی توضیح داده شده و همراه با آنها نیز قطعه کدهایی ارائه شده است. وجود مثالهای عملی در این مستندات نیز خود موضوع بسیار مهمی است. همچنین مستندات در جانگو به صورت نسخهبندی ارائه میگردد.
امیدوارم که توانسته باشم در این مقاله کوتاه راجع به اهمیت موضوع مستندسازی به شما چیزهای مفیدی گفته باشم. اگر ایدهای برای یک مخفف یا سرواژه کلیدی در زمینه مستندسازی دارید خوب است که آن را با ما به اشتراک بگذارید.
من KID را پیشنهاد میدهم: Keep It Documented
دیدگاه و پرسش
در حال دریافت نظرات از سرور، لطفا منتظر بمانید
در حال دریافت نظرات از سرور، لطفا منتظر بمانید