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

۱ ) کامنت نباید کد رو تکرار کند

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

i += 1; // add one to i

۲ ) کامنت خوب کد بد رو توجیه نمی‌کنه

یکی از اصول کد تمیز نوشتن کد هایی هست که self-documenting هستند. یعنی موقع خوندن کد متوجه می‌شید که چه اتفاقی در حال افتادن هست و از اون طرف دیگه نیاز به توضیح دادن کد خودتون ندارید. به عنوان مثال داخل کد زیر اگر اسم خوبی برای متغیر انتخاب کنیم هم کد خوانا تری داریم و هم دیگه کامنت اضافه رو نیاز نداریم.

int a = 22; // a is age

۳ ) اگر کامنت واضحی برای کدتون نمی‌تونید بنویسید احتمالا مشکلی داخل کد وجود داره

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

۴ ) کامنت باید ابهام رو از بین ببره، نه اینکه خودش باعث ابهام بشه

اگر کامنت شما ابهام کدتون رو از بین نمی‌بره و خودش هم باعث ابهام میشه پس بهتره که اصلا کامنت ننویسید. یادتون باشه که کد بدون کامنت، بهتره از کدی که کامنت بد داره.

۵ ) کد های غیر مصطلح (unidiomatic) رو در کامنت توضیح بدید

گاهی وقت ها کد هایی هستند که اگر دیگران اون ها رو ببینن احتمالا میگن که این کد اضافه هست. یا این کد کار خاصی رو انجام نمیده. اینجور وقت ها بهترین کار این هست که با یک کامنت کوتاه و ساده کد رو توضیح بدین و جلوی این مشکل رو بگیرید.

۶ ) اگر کدی رو از جایی کپی کردید داخل کامنت ها به منبع اصلی لینک بدید

خیلی وقت ها پیش میاد که کدی رو از داخل استک اورفلو کپی می‌کنیم. یک کار خوب این هست که داخل کامنت ها لینک مربوط به پستی که ازش کد رو کپی کردیم بزاریم. این کار باعث میشه که اگر در آینده کسی توی این قسمت از کد به مشکل خورد بتونه بفهمه دلیل این مشکل چی بوده، کامنت ها و نظرات بقیه در مورد این قطعه کد رو بخونه و اگر مشکلی هست یا راه بهتری هست اون رو جایگزین کنه.

۷ ) اگر لینک دادن به منبع های خارجی مفید هست توی کامنت ها این کار رو بکنید

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

۸ ) وقتی باگی رو برطرف می‌کنید کامنت بزارید

نوشتن کامنت فقط مربوط به زمانی که کد رو می‌نویسیم نیست و حتی زمانی که یک باگ رو حل می‌کنیم یک کامنت کوتاه می‌تونه مشخص بکنه که قطعه کد ما توی چه شرایطی اجرا می‌شه و چه مشکلی رو حل می‌کنه. اگر نیاز هم به توضیح دقیق تر یا طولانی تر هست می‌تونیم از روش های ۶ و ۷ استفاده کنیم.

۹ ) اگر پیاده سازی قسمتی از کد هنوز انجام نشده، اون قسمت رو با کامنت مشخص کنید

اگر قسمتی از کد به عنوان یک بدهی فنی هست و بعدا باید کامل بشه یا به هر دلیل دیگه ای الان نمی‌تونید تکمیلش کنید کافیه یک TODO رو کامنت کنید و حتی بهتره که یک ایشو برای این قسمت از کد تعریف کنید و لینک ایشو رو داخل کامنت ها قرار بدید.

مورد هایی که تا اینجا خوندید رو از این لینک گذاشتم. اگر خواستید حتما به لینک اصلی هم سر بزنید. نکته ای که خوبه بهش دقت کنیم این هست که توی استفاده از کامنت زیاده روی نکنیم. تکنیک هایی مثل نوشتن کد تمیز یا نوشتن تست هایی که حالت های مختلف رو بررسی می‌کنه باعث می‌شه که کمتر از کامنت استفاده کنیم. نه اینکه کامنت چیز بدی باشه اما اعتدال توی استفاده از کامنت رو باید در نظر داشته باشیم.