آیا روش مورد تأییدی برای کامنت‌گذاری در کدها وجود دارد؟

آیا روش مورد تأییدی برای کامنت‌گذاری در کدها وجود دارد؟

شاید شما نیز گهگاهی به این مسأله فکر کرده باشید که بهترین راه کامنت‌گذاری در سورس‌کد چیست؟ چیزی که بسیاری از افراد در مورد آن به نتیجه نرسیده‌اند! در پاسخ به این سؤال، برخی اعتقاد دارند که راه مشخصی برای این‌منظور وجود دارد و برخی هم با این دیدگاه مخالفند. افرادی هم هستند که عقیده دارند جواب این سؤال بستگی به مهارت‌های برنامه‌نویسی دولوپر دارد. برای یافتن پاسخی روشن، در این مقاله با ما همراه باشید.

در مورد کامنت‌گذاری، برنامه‌نویس‌ها به ۲ دستهٔ کلی تقسیم می‌شوند؛ اولین گروه معتقدند «کد درست‌و‌حسابی، احتیاجی به کامنت‌گذاری ندارد» و گروه دوم می‌گویند «یکی از اصول حرفه‌ای بودن، نوشتن کامنت است».

به عقیدهٔ گروه اول، اگر نیاز به نوشتن کامنت دارید، احتمالاً قسمتی از کدهای‌تان نیاز به ریفکتور و تغییر دارد! اما اگر آن چیزی که نیاز به ریفکتور دارد تحت کنترل شما نیست، نوشتن کامنت بلامانع است. گروه دوم هم بر این باورند که اگر واقعاً اهمیت نوشتن کامنت را زیر سؤال می‌برید، باید بگوییم شما جزو برنامه‌نویس‌های تازه‌کار و غیرحرفه‌ای محسوب می‌شوید؛ نوشتن کامنت برای یک پروژهٔ نرم‌افزاری، کاملاً حیاتی است.

کامنت‌گذاری یا نادیده گرفتن آن، مسئله این است!
هنگامی که ۲ طرف یک اختلاف‌نظر سیاسی به مشکل برمی‌خورند، کار دیپلمات‌ها این است که زمینه‌های مشترک را برای حل اختلاف‌شان پیدا کرده و مشکل را به حداقل برسانند؛ به همین منوال، در کامنت‌نویسی نیز توضیح چراها، به درک این مطلب کمک می‌کند.

برای روشن‌تر شدن این مسئله، به قانونی در استک اورفلو اشاره می‌کنیم با این مضمون که برنامه‌نویس‌های خوب کدهای خود را کامنت‌گذاری می‌کنند؛ برنامه‌نویس‌های عالی به شما می‌گویند که چرا روش خاصی را انتخاب کرده‌اند و استادان برنامه‌نویسی به شما می‌گویند که چرا از روش‌های دیگر استفاده نکرده‌اند! Jeff Atwood -خالق استک اورفلو- چندین مرتبه این موضوع را بیان کرده است به این شکل که:

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

آیا می‌دانستید که بزرگترین مشکل کامنت‌گذاری چیست؟
تا به این‌جا، دیدگاه‌های مختلف را بررسی کردیم؛ حال قصد داریم به منطق پشت پردهٔ این قضیه بپردازیم. کامنت‌ها هدف مشخصی دارند و آن هم چیزی نیست جز ارتباط با مخاطب و روشن کردن مسأله‌ای خاص؛ ولی یک نکتهٔ منفی نیز در این باره وجود دارد و آن‌هم این‌که نوشتن کامنت زمان‌بر است.

اگر مسأله میان زمان صرف‌شده برای کامنت‌نویسی و فواید آن بود، این مسئله به‌راحتی قابل‌حل بود ولی کامنت‌ها یک ویژگی بد دیگر نیز دارند و آن‌هم این‌که در طولانی مدت، اغلب آن‌ها به‌اصطلاح Out of Date شده و اطلاعات نادرستی را به دولوپر بعدی منتقل می‌کنند. به‌عنوان مثال:

//Returns x + y or, if x or y is less than zero, throws an exception
public int Add(int x, int y)
{
    return x + y;
}

متوجه شدید؟ وقتی به مواردی شبیه به مثال بالا برخورد می‌کنید، می‌فهمید که قبلاً عبارتی در قسمت مورد نظر وجود داشته است؛ فردی آن‌را پاک کرده ولی به خود زحمت نداده تا کامنتی که دیگر بی‌ربط به‌نظر می‌رسد را تغییر دهد!

این نمونه، یکی از مشکلات اساسی و ریشه‌ای در نوشتن کامنت است؛ مخصوصاً این‌که کامنت را به‌عنوان نمایندهٔ ارتباط میان کدهای کامپایل/اجرا نشده و اطلاعات متا دربارهٔ کدها به‌کار ببریم.

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

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

این‌که کدام گروه نظر درستی دارند را نمی‌توان باقاطعیت بیان کرد؛ گفتن این‌که همهٔ دولوپرها موظفند قسمت‌هایی از کد را با کامنت توضیح دهند، مسئولیتی را به‌دوش ایشان اضافه خواهد کرد که مسلماً برخی افراد با آن موافق نخواهند بود. با این کار، افراد را موظف به انجام کاری می‌کنید که از آن متنفر هستند؛ آن‌ها این کار را انجام نمی‌دهند و اگر هم انجام بدهند، با نارضایتی است و درنتیجه کیفیت پایینی خواهد داشت و دردی را دوا نخواهد کرد!

چند توصیه برای نوشتن کامنت‌های کاربردی
شاید شما نوشتن کامنت را از استانداردهای حرفه‌ای‌گری به‌حساب بیاورید و جزو گروهی هستید که با این کار موافقند اما این کار در بیشتر اوقات شما را به ایجاد بحث با دیگران سوق می‌دهد؛ اگر برای نوشتن کامنت‌ها بی‌وقفه و سخت کار نکنید، پیشرفت آن‌ها کند خواهد بود و اغلب اوقات نتیجهٔ عکس خواهند داشت. بنابراین بهترین راهی که می‌توان پیشنهاد کرد این است که تا جای ممکن از نوشتن کامنت‌ها خودداری کنید.

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

اما درعین‌حال مدنظر داشته باشید که گاهی‌اوقات، شرایطی به‌وجود می‌آید که نیاز به کامنت‌گذاری کاملاً حس می‌شود؛ مثلاً برخی سازمان‌ها تعهداتی به‌عنوان کامنت‌های قانونی و مربوط به کپی‌رایت در هر فایل دارند. درنتیجه باید این کامنت‌ها را به کدهای‌تان اضافه کنید (برای این کار ممکن است نیاز به یک Generator یا چیزی داشته باشید که به‌طور خودکار این کار را برای‌تان انجام دهد تا از اتلاف وقت جلوگیری کنید).

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

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

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

حال نوبت به نظرات شما می‌رسد؛ شما با کدام دیدگاه در مورد کامنت‌گذاری موافق هستید؟ نظرات، تجربیات و دیدگاه‌های خود را در این رابطه با ما و سایر کاربران سکان آکادمی به اشتراک بگذارید.

منبع


مرتضی صمدی