کامنت‌نویسی در کد چیست و چه زمانی مفید یا مضر است؟

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

جملهٔ کلیشه‌ای «کد خوب خودمستند است» نیمی درست است: نام‌گذاری و ساختار خوب، نیاز به توضیح چیستی را کم می‌کند. نیم دیگر این است که «چرا» و «قید بیرونی» اغلب در کد دیده نمی‌شوند — و همان‌جاست که کامنت ارزش دارد.

این مقاله مرز مفید/مضر، انواع کامنت، پیوند با Review و README، و قواعد تیمی کوتاه را می‌دهد تا بحث سلیقه‌ای نشود.

پاسخ کوتاه

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

TODO بدون صاحب و تاریخ بدهی پنهان است. Docstring و API docs برای قرارداد عمومی مفیدند. Secret و کلید را هرگز در کامنت نگذارید — تاریخچهٔ Git آن را نگه می‌دارد.

بهترین کامنت اغلب بعد از refactor بی‌نیاز می‌شود؛ دومین بهترین، چرایی کوتاهی است که کد نمی‌تواند بگوید.

کامنت چه چیزی را باید بگوید؟

• چرایی تصمیم: چرا این الگوریتم نه آن یکی؛ چرا این کتابخانه.
• قید بیرونی: محدودیت API فروشنده، قانون کسب‌وکار، باگ شناخته‌شدهٔ Upstream با لینک Issue.
• هشدار ایمنی: این ترتیب فراخوانی مهم است؛ این حلقه Concurrent نیست.
• معنای عدد جادویی اگر نمی‌توانید نام ثابت واضح بسازید — ترجیحاً نام بسازید.

اگر می‌نویسید «i را یکی زیاد کن»، کامنت نیست؛ دوباره‌نویسی کد با کلمات است. اگر می‌نویسید «پرداخت باید قبل از کاهش موجودی ثبت شود وگرنه در crash دوبار شارژ می‌شویم»، ارزش دارد.

جدول مفید در برابر مضر

کد Comment‌شده به‌جای حذف

نگه‌داشتن سی خط کد قدیمی داخل /* ... */ معمولاً از ترس از دست دادن تاریخچه است. Git همان تاریخچه را دارد. کد مرده Review را شلوغ می‌کند و گاهی بعداً اشتباهاً Uncomment می‌شود. اگر موقتاً لازم است، با TODO صاحب‌دار و تاریخ انقضا علامت بزنید یا پشت Feature Flag بگذارید.

TODO، FIXME و بدهی

1. TODO باید مسئله، مالک یا تیم، و معیار اتمام داشته باشد.
2. FIXME برای باگ شناخته‌شده است نه سلیقه.
3. اسکن دوره‌ای TODO در CI یا تقویم Tech Lead جلوی فراموشی را می‌گیرد.
4. اگر TODO بیشتر از یک Sprint عمر کرد، به Issue منتقلش کنید.

تیم‌هایی که صدها TODO بدون Issue دارند، در عمل اولویت ندارند؛ فقط عذاب وجدان متنی دارند.

کامنت در Code Review

Reviewر خوب به‌جای دستور «کامنت بگذار» می‌پرسد: نام بهتری ممکن است؟ تابع کوچک‌تر می‌شود؟ اگر بعد از آن هنوز ابهام دامنه ماند، آن‌وقت کامنت. نویسنده هم نباید با دیوار متن، طراحی ضعیف را دفاع کند.

Docstring و مستند جدا

Docstring نوع API برای مصرف‌کنندهٔ تابع/ماژول‌اند: ورودی، خروجی، خطا،اثر جانبی. جزئیات معماری سیستم جای README و docs است نه بالای هر حلقه. قاطی کردن این لایه‌ها باعث می‌شود هم کد شلوغ شود هم سند واقعی نوشته نشود.

قواعد عملی کوتاه برای تیم

• اول نام و ساختار؛ بعد کامنت.
• کامنت را در همان PR با کد به‌روز کنید؛ کامنت دروغ بدتر از نبود کامنت است.
• زبان کامنت را یکی کنید (مثلاً فارسی برای دامنهٔ کسب‌وکار داخلی، انگلیسی برای پروژهٔ OSS).
• از کامنت برای ردیابی نویسنده استفاده نکنید؛ Git blame هست.
• هیچ Secretای در کامنت.

نمونه‌های کوتاه

مضر:

javascript

// set user name user.name = name;

مفیدتر:

javascript

// Billing vendor rejects Unicode in display name; strip to keep invoice sync. user.displayName = asciiOnly(name);

در مثال دوم، بدون کامنت ممکن است کسی فیلتر را «پاکسازی بی‌ضرر» بداند و حذف کند.

برای مدیر غیرتکنیکال

وقتی مهندس می‌گوید وقت می‌گذارد تا کد را خوانا کند، این جایگزینی لوکس برای فیچر نیست؛ کاهش هزینهٔ نفر بعدی است. اجبار به «هر خط یک کامنت» کیفیت نمی‌آورد؛ اجبار به Review و نام‌گذاری بهتر می‌آورد.

جمع‌بندی برای تصمیم

کامنت ابزار ارتباطی است نه دکوراسیون. مفید وقتی چرایی و قید را می‌گوید؛ مضر وقتی بدیهیات را تکرار می‌کند، کهنه می‌ماند، یا بوی طراحی بد را می‌پوشاند. Secret را در کامنت نگذارید. TODO را به Issue وصل کنید.

یک عادت این هفته: در Review بعدی، یک کامنت بدیهی را حذف و یک چرایی جایش بنویسید — یا کد را طوری عوض کنید که هیچ‌کدام لازم نباشد.

کامنت و نام‌گذاری هم‌خانواده

قبل از نوشتن کامنت طولانی، نام تابع، متغیر و نوع را دوباره بخوانید. اگر نام invertMatrixForLegacyBilling لازم شد تا فهمیده شود، آن نام بهتر از تابع f و یک پاراگراف کامنت است. کامنت باید باقیماندهٔ ابهامی باشد که نام نمی‌تواند حمل کند.

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

کامنت در کد تولیدشده و کد AI

کد تولیدشده توسط ابزار AI اغلب کامنت‌های بدیهی یا نادرست دارد. قبل از Commit، کامنت‌ها را مثل کد Review کنید. اگر خودتان نمی‌فهمید چرا یک خط هست، کامنت تزئینی کمکتان نمی‌کند — باید رفتار را بفهمید یا حذفش کنید.

هرگز از مدل نخواهید Secret را داخل کامنت نمونه بگذارد. Placeholder صریح بهتر است.

استاندارد تیم بدون پلیس

یک صفحهٔ کوتاه در docs کافی است: چه چیزهایی را کامنت می‌کنیم، زبان کامنت، ممنوعیت کد مرده، و مثال خوب/بد. Linterهایی که روی طول یا TODO قاعده می‌گذارند مکمل‌اند نه جایگزین قضاوت.

اجبار به درصد پوشش کامنت معمولاً کیفیت را پایین می‌آورد چون مردم متن بی‌معنا تولید می‌کنند تا متریک سبز شود.

کامنت، بدهی فنی و محصول

وقتی کامنت می‌گوید به خاطر فشار زمانی این میانبر را زدیم، آن را به Issue وصل کنید و تاریخ بگذارید. در غیر این صورت میانبر دائمی می‌شود. مالک محصول باید بداند بعضی میانبرها هزینهٔ نگهداری بعدی دارند؛ کامنت به‌تنهایی اولویت را عوض نمی‌کند.

مثال‌های دامنهٔ فارسی

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

جمع‌بندی میدانی

در PR بعدی سه کار کنید: یک کامنت بدیهی را حذف کنید، یک چرایی به جا اضافه کنید، و یک TODO را به Issue تبدیل کنید. این سه حرکت بیش از نوشتن راهنمای بیست‌صفحه‌ای فرهنگ را جابه‌جا می‌کند.

منابع و مراجع

• این مطلب مفهومی است و به ادعای آماری یا صفحهٔ محصول خاص وابسته نیست؛ برای جریان همکاری به مستندات Pull Request در مقالات ۰۷۸ و ۰۷۹ و برای ورودی پروژه به README در ۰۸۴ رجوع کنید.
• GitHub Docs — About pull request reviews — https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews

لایهٔ بالاتر از کامنت، Documentation سیستمی است که در مقالهٔ بعد می‌آید.