بچه‌های برنامه‌نویس چه جونیور و چه سنیور، خوب می‌دانند خودکامنتی یعنی چه؟
مثلاً از ترس فراموشی و یا برای یادآوری و مستندسازی در هر کد و تابعی، یک توضیح مختصری را می‌نویسند که کار درستی است.
فاجعه آن‌جاست که گاهی این کامنت‌ها را از بس بد و نامفهوم می‌نویسند که بعدها هم خودشان نمی‌فهمند چی بود!
با این‌وجود اکثرشان این یادداشت را برای خودشان می‌نویسند وگرنه اگر برای دیگران باشد تاجایی که بتوانند انجامش نمی‌دهند تا دست یارو توی پوست گردو بماند. به‌ندرت پیش می‌آید برنامه‌نویسی برای کمک به درک بهتر دیگران، اقدام به ثبت یک کامنت قابل‌فهم در کد کند.
×××
بطور مثال این یک خودکامنتی در کد پایتون است:
# این تابع برای محاسبه مجموع دو عدد استفاده می‌شود.
def add(a, b):
return a + b
×××
خودکامنتی، یعنی چیزی نوشتی و می‌ترسی که بعداً نفهمی چیست!
این کامنت، نشان می‌دهد یا کدت شفاف و واضح نیست و یا کلاً فراموشکار هستی و یا کپی کردی کد را بی‌آنکه درکش کرده باشی.
کد و کامنت هر دو بوضوح هدف تابع را توضیح می‌دهند، اما اگر نام تابع به اندازه‌ي کافی گویا باشد (مثل add)، ممکن است کامنت نویسی ضرورتی نداشته باشد.
نام‌های معنادار و توصیفی برای توابع و متغیرها می‌تواند تا حد زیادی نیاز به کامنت‌های اضافی را کاهش دهد.
از طرفی، اگر تابعی که نوشتی خیلی پیچیده است باید سند مفصل یا دایکومنت برایش داشته باشی و به یک کامنت بسنده نکنی.
درست شبیه نویسنده‌ای که تلاش می‌کند مطلبی را بطور کامل و حتی طولانی شرح دهد تا کمترین نیاز به حاشیه‌نویسی باشد. یا اگر خیلی پیچیده نوشته باشد کتاب یا نوشته‌ای دیگر در باب شرح آن قبلی می‌نویسد.
×××
چیزی که برای خودت و دیگران قابل فهم است کامنت‌نویسی نیاز ندارد!
www.Soroushane.ir
