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