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

گردآوری و تالیف : ارسطو عباسی
تاریخ انتشار : 19 شهریور 1397
دسته بندی ها : برنامه نویسی

وقتی وارد دنیای توسعه نرم افزار می‌شویم، با اصطلاحات بسیاری روبرو خواهیم شد. KISS، DRY، SOLID و... . اما وقتی موضوع به مستندسازی یا کامنت کردن کدهای‌تان می‌رسد چنین کلمات دلفریبی را زیاد نمی‌بینید.

چرا اینگونه است؟

مستندسازی دقیقا باید به اندازه دیگر جنبه‌های فرایند توسعه برای افراد برنامه‌نویس مهم باشد.

در این مقاله به شما می‌گویم که چرا مستندسازی از شما توسعه‌دهنده و مشارکت کننده بهتری در تیم‌تان می‌سازد.

هیچکسی زمان برای انجام این کار را ندارد

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

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

کمترین جزئیات همواره می‌توانند مهمترین تفاوت‌ها را در آینده شکل دهند.

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

همچنین با قسمت‌هایی از کدهای‌تان برخورد خواهید کرد که در مورد آن‌ها شک دارید، تنها راه‌حلی که می‌تواند تمام این مسائل را واضح بکند، مستندسازی است. 

تعیین زمان کمی برای نوشتن و توضیح دادن آنچه که نوشته‌اید، می‌تواند مدت زمان بسیار زیادی را در آینده برای‌تان نجات دهد. 

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

جدای از تمام این‌ها، وقتی که شما به عنوان یک توسعه‌دهنده قصد دارید تا چیزی را در رابطه با کدنویسی یاد بگیرید چه کاری را انجام می‌دهید؟

به سراغ مستندات می‌روی!

کدی که خوب نوشته شده باشد نیازی به مستندسازی ندارد

همواره این موضوع را به من می‌گویند و قضیه را به خوبی می‌دانم. کدهایی که خوب نوشته شده باشند نیازی به مستندسازی ندارند.

در حالیکه ممکن است چنین موضوعی واقعیت داشته باشد اما این بدان معنا نیست که حتما باید از مستندسازی دوری کنیم. در اینجا می‌توانید دلیل آن را مشاهده کنید:

  • همه ما با کدهای قدرتمندی آشنا هستیم که یک ویژگی را ارائه می‌دهند. اما گاهی اوقات یک قسمت از کد به صورت واضح ارتباط‌ش را با دیگر قسمت‌های کد نشان نمی‌دهد. به همین دلیل این موضوع باید توضیح داده شود.
  • هر سرویسی که ایجاد می‌کنید ممکن است شامل یک یا چند API منحصر به فرد شود. شیوه استفاده از این APIها نیازمند نوشتن مستندات می‌شود. مستنداتی که بتوان آن‌ها را خارج از کدها مطالعه کرد. 
  • همکاران در یک شرکت بزرگ معمولا در دپارتمان‌های مختلفی کار می‌کنند، به همین دلیل در صورتی که همه آن‌ها توسعه‌دهنده نباشند ممکن است درک چیزهایی که به صورت کد نوشته‌اید برای‌شان سخت باشد.
  • خود حقیقت نیز ممکن است باعث شود که شما نگاهی متفاوت با آنچه که نوشته‌اید داشته باشید. توضیح اینکه کدتان چه کاری را انجام می‌دهد به شما و دیگران این قابلیت را می‌دهد که تنها منتظر کارهایی باشید که انتظارش را دارید و با چیزهای عجیب و غریب روبرو نشوید.

چگونه مستندات خوبی بنویسیم؟

مستندات خوب مانند یک بلاک خوب کد هستند. کوتاه، ساده و درک پذیری آسان. در زیر می‌توانید چند نکته کمکی برای نوشتن مستندات را دنبال کنید:

  • جامعه هدف مستندسازی را شناسایی کنید. آیا این مستندات تنها برای توسعه‌دهندگان نوشته می‌شود؟ آیا مخاطبین بیشتری را در بر می‌گیرد؟ درک این موضوع می‌تواند در زمان‌تان نقش بسیار مفیدی ایفا کند. با در نظر گرفتن مخاطبان‌تان حال می‌دانید که دقیقا به چه شکلی مباحث را توضیح دهید.
  • هدف اصلی چیزی که ساخته‌اید را به صورت کوتاه و در عین حال مفهومی بنویسید. این موضوع به خوانندگان کمک می‌کند تا هدف هر یک از ویژگی‌های نرم افزار را درک کنند و مواردی که خودشان می‌خواهند را ارزیابی نمایند.
  • چشم‌اندازهای آینده را لیست کنید و شرح دهید، مطمئن شوید که به تمام مستقلات و نیازمندی‌های مربوط به پروژه‌تان اشاره می‌کنید.
  • مطمئن شوید که مستندات را براساس نسخه‌های نرم افزاری می‌نویسید، به این صورت خوانندگان می‌تواند اعتبار بیشتری را در مستندسازی‌تان ببینند. همچنین اگر از کتابخانه معینی استفاده می‌کنید، مطمئن شوید که آن را نیز در نسخه‌های مستندسازی‌تان قرار خواهید داد.
  • در رابطه با مثال‌های کدنویسی سخاوتمندانه رفتار کنید. در رابطه با پیاده‌سازی هر کدام از ویژگی‌ها به صورت مفصل شرح دهید و خروجی‌های مورد انتظار را نشان دهید.

نمونه‌ها

در ادامه با ارائه چند مثال قصد داریم یک نمونه‌هایی از مستندسازی‌های خوبی را به شما نشان دهیم:

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

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

در مستندات Stripe هر موضوعی قطعه کدهایی را شامل می‌شود که می‌توان آن را در زبان‌های کدنویسی مختلفی مشاهده نمود.

مستندات جانگو بسیار قدرتمند است. مهم نیست که در چه سطحی از کدنویسی قرار دارید، می‌توانید با آموزش‌های جانگو همراه باشید.

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

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

من KID را پیشنهاد می‌دهم: Keep It Documented

منبع

مقالات پیشنهادی

Full-Stack Designer کيست و چرا بايد يکي از آنها باشيد

سريع بودن و موثر واقع شدن در مهارت ها و تمركز روي زندگي حرفه اي مون ارزش زيادي داره . عنواني كه ما استفاده ميكنيم ميتونه به شكل موثري به ديگران بگه ك...

زبان های محبوب طراحی وبسایت. چه‌کاری کاری انجام می‌دهند و چرا شما باید از آن‌ها استفاده کنید

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

آیا پروژه ای که روی آن کار می کنید دیگر برایتان جذاب نیست؟

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

رابط کاربری محاوره‌ای چیست و چرا اهمیت دارد؟

رابط کاربری محاوره‌ای یک تجربه ساده از یک چت بات است که سعی می‌کند زبان انسان را به صورت طبیعی پردازش کند، درست مانند حالتی که شما با استفاده از متن ی...