اصول Comment گذاری در کدها

• Comment ها باید کوتاه و شفاف باشند. هدف این است که برنامه نویس بتواند به سرعت متوجه منظور شما شود.
• منظور Comment نباید کد را مجدد تکرار کند.
• ترجیحاً از زبان انگلیسی برای نوشتن Comment استفاده کنید. (مگر اینکه تیم شما زبان دیگری را ترجیح دهد)
• از نوشتن Comment های غیرمفید خودداری کنید.
• برای تعیین کارهایی که باید بعداً انجام شوند یا مشکلاتی که باید حل شوند، از نشانگرهای Comment استفاده کنید:

// TODO: Optimize this function for better performance.
public void calculateDate()
{
}

# FIXME: Handle edge case when input is None.
function getData()
{
}

TODO: برای کارهای معلق/آینده

FIXME: برای اصلاحات ضروری

NOTE: برای توضیحات مهم

HACK: برای راه‌ حل‌ های موقت/trick

• Comment، به معنای توجیهی برای کد نامفهوم نیست!
• وقتی نمی‌ توانید Comment واضحی و شفافی برای کد بنویسید، معمولاً نشان دهنده این است که کدتان مشکل دارد.پس احتمالاً کد باید بازنویسی/ساده‌ سازی شود.
• Comment ها باید ابهامات را برطرف کنند، نه اینکه ابهام جدید ایجاد کنند!
• اگر Comment طولانی است، از Comment نوع multi-line برای نوشتن آن استفاده کنید.

/*
 This function calculates the Fibonacci sequence up to n.
 It uses an iterative approach to improve performance compared
  to the recursive method, which can be slow for large values of n.
 Also blah blah.
 */

• Comment ها را بروز نگه دارید.
• همیشه فقط کدهای غیر معمول/پیجیده را در Comment توضیح دهید.
• هنگام Comment نویسی، اصول و ساختار مخصوص هر زبان برنامه نویسی را حفظ و رعایت کنید.

/**
 * Calculates the sum of two numbers.
 *
 * @param int $a The first number
 * @param int $b The second number
 * @return int The sum of $a and $b
 */
function add(int $a, int $b): int {
    return $a + $b;
}

/// <summary>
/// Calculates the sum of two numbers.
/// </summary>
/// <param name="a">The first number</param>
/// <param name="b">The second number</param>
/// <returns>The sum of a and b</returns>
public int Add(int a, int b)
{
    return a + b;
}

• بهتره همیشه لینک منبع اصلی کدهای کپی‌ شده را در Comment قید کنید.
• اگر الگوریتمی پیچیده است، می‌ توانید قبل از پیاده‌ سازی آن، Pseudo code آن را به صورت Comment بنویسید.

# Pseudo code:
# 1. Initialize an empty list
# 2. Loop through the input array
# 3. Append each element multiplied by 2 to the list
result = []
for num in input_array:
    result.append(num * 2)

• اگر کد شما به اندازه کافی خوانا و واضح است، نیازی به نوشتن Comment ندارد. (کد گویا بهتر است)

// Returns result of calculation!
return a + b

• از نوشتن Comment هایی که فقط شامل نظرات شخصی، شوخی یا مطالب های غیرضروری هستند، باید اجتناب شود.
• از Comment برای نشان دادن محدودیت‌ ها/خطرات/هشدارها استفاده کنید.

// WARNING: This function does not handle negative inputs!
function squareRoot($x)
{
    return $x ** 0.5;
}

• اگر از یک الگوی طراحی خاص (Singleton، Factory و...) استفاده می‌ کنید، آن را در Comment ها می توانید ذکر کنید.

// Singleton pattern implementation.
class DatabaseConnection:
    ...

• اگر متغیرها و توابع نام‌ گذاری خوبی داشته باشند، نیاز به Comment کمتر می‌ شود.
• و در آخر، کد خوب مثل یک داستان است؛ Comment ها فقط پاورقی‌ های آن هستند...