کامنت گذاری در کد، یک شمشیر دو لبه است. اگر به درستی انجام شود، می تواند طراحی سیستم را بهتر کند و در غیر این صورت، بسیار آسیب زننده است.
کامنت گذاری در واقع مستندسازی کد است. ولی بسیاری از برنامه نویس ها معتقدند که کامنت فقط باعث اتلاف وقت می شود. حتی کسانی که هم معتقدند کامنت گذاری مفید است، خیلی کم این کار را انجام می دهند. به همین دلیل، در اکثر سازمان ها، بخش های بسیاری از کد بدون کامنت است.
معمولا برنامه نویس ها 4 بهانه برای ننوشتن کامنت دارند:
این بهانه ها را بررسی کنیم:
بعضی افراد باور دارند که اگر کد خوب نوشته شود، به کامنت گذاری نیازی نیست. قطعا همه ی ما دوست داریم این جمله را باور کنیم، ولی در نهایت، اشتباه است. البته قطعا کارهایی هست که می توان انجام داد تا نیاز به کامنت گذاری کمتر شود. مثلا این که برای متغیرها اسم مناسب انتخاب کنیم. ولی باز هم اطلاعات زیادی وجود دارد، که آن ها را نمی توان در کد نشان داد.
برای مثال، در یک کلاس، فقط بخش کوچکی از واسط آن، مثل signature متدها را می توان در کد مشخص کرد. ولی این که هر متد دقیقا چه کاری انجام می دهد، یا معنی خروجی آن چیست، تنها از طریق کامنت گذاری قابل انتقال به خواننده ی کد است. چیزهای دیگری هم هست که در کد قابل توضیح دادن نیست، مثلا این که چرا یک طراحیِ به خصوص برای بخشی از کد انتخاب شده و یا چرا یک متدِ بخصوص صدا زده شده است.
بعضی برنامه نویس ها معتقدند که برای دانستن این که یک متد چه کاری انجام می دهد، باید کد آن را خواند نه این که از طریق کامنت متوجه آن شد. ولی آیا این کار عقلانی است؟ آیا باعث اتلاف وقت نمی شود؟ شاید در یک نرم افزار کوچک این کار امکان پذیر باشد، ولی در سیستم های بزرگ، خواندن کدِ متد برای فهمیدن رفتار آن، روش کاربردی نیست.
علاوه بر این، کامنت ها برای انتزاع، ضروری هستند. همانطور که در مطلب برنامه نویسی ماژولار اشاره شد، هدف از انتزاع، پنهان کردن پیچیدگی است. انتزاع، یک نمای ساده شده از یک موجودیت است، که اطلاعات ضروری (برای آن انتزاع) را حفظ می کند، و هر اطلاعات اضافه ای را دور می ریزد. اگر برای استفاده از یک قطعه کد، افراد مجبور باشند کد آن را بخوانند، پس انتزاعی وجود ندارد و همه ی پیچیدگی آن قطعه از کد، در معرض دنیای بیرون قرار گرفته است. در مورد متدها، اگر یک متد کامنت نداشته باشد، تمام انتزاع آن، شامل نام متد و نوع پارامتر های ورودی و خروجی آن است.
برای مثال فرض کنید یک متد داریم، که یک بخش از یک string را استخراج می کند. این متد دو ورودی دارد، start و end که مشخص کننده ی شروع و پایان ِ قسمتی از string هستند که باید جدا شود. قطعا از ظاهر این متد، نمی توان تشخیص داد که آیا string خروجی، شامل کاراکترهایی که در start و end هستند هم می شود؟ یا فقط هر آنچه بین این دو عدد است را جدا می کند؟ برای فهمیدن این سوال، استفاده کننده، باید کد را بخواند تا بتواند از این متد استفاده کند.
بنابراین اگر می خواهید از انتزاع استفاده کنید تا پیچیدگی را پنهان کنید، با استفاده از کامنت بهتر می توانید این کار را انجام دهید.
معمولا برنامه نویس ها، اولویت کامنت گذاری را پایین تر از انجام سایر وظایف در نظر می گیرند. بین این که یک بخش جدید را توسعه دهند، یا این که برای کدی که قبلا نوشته اند کامنت بنویسند، معمولا اولی را انتخاب می کنند. همه می دانیم که پروژه های نرم افزاری، تقریبا همیشه از نظر زمانی تحت فشار هستند و در اکثر مواقع، کارهای زیادی هست که اولویت آن ها از کامنت گذاری بالاتر به نظر می رسد.
ولی باید از دیدگاه سرمایه گذاری به این مساله نگاه کرد. اگر یک نرم افزار با ساختار تمیزتر می خواهید، که در بلندمدت، عملکردِ شما را بهتر می کند و سرعت توسعه را بیشتر، باید در کوتاه مدت، زمانی را به ساختن این ساختار تمیز اختصاص دهید. کامنت های خوب، کمک بسیاری به نگهداری یک سیستم نرم افزاری می کنند و زمانی که برای کامنت گذاری صرف می شود، در آینده سود ده خواهد بود.
علاوه بر این، کامنت گذاری قرار نیست زمانِ زیادی از شما بگیرد. در نظر بگیرید که شما برای تایپ کردن کد چقدر زمان می گذارید و مقایسه کنید با زمانِ تخصیص داده شده به تحلیل، طراحی، کامپایل کردن کد و تست آن. احتمالا این زمان بیشتر از 10 درصد نخواهد بود. تایپ کردن کامنت هم دقیقا همینطور است. نهایتا باید 10 درصد از زمان را به آن اختصاص داد، و این مستند سازی، اگر به درستی انجام شود، این هزینه را به خوبی جبران خواهد کرد.
درست است. بعضی کامنت ها ممکن است در طول زمان اعتبار خود را از دست بدهند. ولی دقت کنید زمانی کامنت بی اعتبار می شود، که تغییرات گسترده در کد اعمال شده باشد و اعمال این تغییرات، قطعا زمان خیلی بیشتری از تغییر کامنت ها از شما خواهد گرفت. اگر کامنت ها، از نظر جایگاه در کد، نزدیک کدی باشند که به آن مربوط است، می توان در زمان تغییر کد، به سادگی و با صرف زمان کم، کامنت را هم تغییر داد و از منقضی شدن آن جلوگیری کرد.
قطعا هر مهندس نرم افزار، در طول دوره ی کاری خود، کامنت هایی را دیده است که هیچ اطلاعات مفیدی در خود نداشته اند و هیچ کمکی به مستندسازی نرم افزار نکرده اند.
ولی این دلیلی برای حذف کامنت گذاری از روال توسعه ی نرم افزار نیست. وقتی افراد یاد بگیرند چگونه کامنت بنویسند و یک چهارچوب کلی برای این کار داشته باشند، این مشکل حل خواهد شد. مساله این است که افراد برای نوشتن کامنت نیاز به آموزش دارند و این کاری نیست که صرفا با سلیقه ی شخصی و بدون داشتن چهارچوب و روش های مشخص انجام شود.
در مطلب پیچیدگی در نرم افزار گفته شد که پیچیدگی، به سه صورت خودش را در سیستم نشان می دهد:
یعنی برای یک تغییر کوچک، بخش های زیادی از سیستم را باید تغییر داد.
یعنی برای اعمال یک تغییر، برنامه نویس باید اطلاعات وسیعی از بخش های مختلف سیستم به دست آورد.
یعنی این که چه بخش هایی باید تغییر کنند، یا برای اعمال تغییرات، چه ملاحظاتی باید در نظر گرفته شود، مشخص و شفاف نیست.
کامنت گذاری خوب، می تواند در دو مورد آخر کمک کند. هم می تواند بار شناختی را کم کند. چرا که اطلاعاتی که برنامه نویس برای تغییر بخش هایی از کد باید داشته باشد، به سرعت به او می دهد و چون نیازی به خواندن کد نیست، از هجوم اطلاعات اضافه به ذهن برنامه نویس جلوگیری می شود. همچنین میزان ناشناخته ها کمتر می شود و به راحتی می توان تاثیرِ تغییرات را پیش بینی کرد و آن بخش هایی که به کد فعلی مرتبط است را شناسایی کرد. علت اصلی پیچیدگی در نرم افزار، وابستگی ها هستند و با کامنت گذاری می توان این وابستگی ها را شفاف کرد و ابهام را کاهش داد.
ایده ی کلی کامنت گذاری، نمایش اطلاعاتی است، که در هنگام طراحیِ یک بخش از کد، در ذهن طراح و برنامه نویس بوده است، ولی امکان نشان دادن آن در کد نیست. این اطلاعات شامل جزئیات سطح پایین مانند محدودیت های سخت افزاری که افراد را وادار به یک طراحی خاص می کند، تا جزئیات سطح بالاتر، مثل علت وجودی یک کلاس یا یک ماژول خاص می شود.
وقتی یک برنامه نویسِ دیگر، بعد از گذشت زمان، می خواهد آن ماژول را تغییر دهد، با خواندن کامنت ها، کار خود را بسیار سریعتر انجام می دهد. ولی بدون کامنت، باید آن چه که در ذهن برنامه نویس قبلی بوده را حدس بزند. این اتفاق هم باعث اتلاف وقت می شود، هم این که با حدسِ اشتباه، ممکن است برنامه نویس جدید، کدی بنویسد که منجر به خطا شود.
حتی اگر قرار است همیشه! همان برنامه نویس قبلی روی یک بخش از کد کار کند، باز هم کامنت گذاری لازم است. کافی است فقط چند هفته از زمانی که یک کد را نوشته اید بگذرد، تا جزئیات طراحی و پیاده سازی آن بخش از کد را فراموش کنید.
