در واقعیت کامنت ها واقعا زیاد مفید نیستند. چون نه به عمد، اما اطلاعات خوبی به خواننده ی کد نمی دهند.

کد تغییر می کند و اتفاقات مختلف در آن می افتد. اما کامنت معمولا این تغییرات را همراهی نمی کند. پس کامنت نادقیق خیلی بدتر از نبودن کامنت است.

نکات مورد توجه در مورد کامنت ها:

  • کامنت ها کد های بد را خوب نمی کنند. زمانی که کد گیج کننده ای می نویسیم سعی میکنیم با نوشتن کامنت بدی کد را جبران کنیم، اما بهتر است کامنت را پاک کرده و از اول کد را بنویسیم.
  • کار خود را در کد توضیح دهید. به جای اضافه کردن کامنت سعی کنید کد خود را خوانا بنویسید. چون یک کد تمیز زودتر از یک کد کثیف با کامنت فهمیده می شود.

کامنت های خوب:

  • کامنت های مجاز: که قوانین را اعلام می کنند. مثل کپی رایت.
  • کامنت های آموزنده: مثل کامنتی که فرمت تاریخ و زمان را نشان می دهد.
  • توضیح دادن مقصود: در صورتی که واقعا هدف را بیان کند.
  • شفاف سازی: باز هم اولویت با نوشتن کد شفاف است تا کامنت.
  • هشدار در مورد عواقب: فرض کنید یک متد sleep() داریم که زمان بر است. کامنت در مورد این موضوع می تواند خواننده را آگاه کند.
  • کامنت های To Do: کارهایی که باید انجام شوند اما تا الان انجام نشده اند.
  • تقویت:برای تقویت اهمیت چیزی که ظاهرا مهم به نظر نمی رسد.
  • java doc یا امکانات مشابه در سایر زبان ها

کامنت های بد:

  • کامنت های من من کننده
  • کامنت های زاید: کامنت های که خواندنشان بیشتر از خواندن کد وقت می گیرد.
  • کامنت های گمراه کننده
  • کامنت های اجباری
  • کامنت های ژورنالی: کامنت هایی که مثل لاگ در کد ایجاد می شود مثل نام نویسنده یا ویرایشگر و تاریخ.
  • کامنت های نویز: کامنت هایی که هیچ اطلاعاتی نمی دهند: مثل نوشتن کامنت default constructor
  • Position markers: //////////////// که برای جدا سازی استفاده می شود اگر زیاد باشد مثل نویز می شود و هیچ کمکی نمی کند.
  • کامنت های نزدیک کروشه و براکت ها: مثل end while// {  که وقتی حلقه خیلی طولانی باشد، جای بسته شدن حلقه ها را نشان می دهد. بهتر است به جای این کار طول توابع کمتر شود تا چایان حلقه ها راحت پیدا شود.
  • کد های comment-out: کد هایی که نوشته شده اند بعد کامنت شده و به حال خود رها شده اند.
  • کامنت های غیر محلی: هر کامنت باید نزدیک کد مربوط به خودش باشد.
  • اطلاعات اضافی و بیش از حد در کامنت
  • Function header ها: بهتر است به جای توضیح کار توابع یک نام خوب که کارش را نشان می دهد، انتخاب کنیم.