🔵کد باید به شما بگوید چگونه، کامنت باید بگوید چرا!🔵

فرض کنید کدی به شما تحویل می دهند که مربوط به یک سیستم پرداخت است. فایلی را باز می کنید و چیزی شبیه به این میبینید:

# Parse the JSON response
data = json.loads(response.text)

با خودتان فکر میکنید خب این کامنت به چه دردی می خورد؟ خود کد دقیقا همان کار را می کند. سوال این است که چرا چنین فایلی اصلا خوانده و پارس می شود؟ این کد چه فرض هایی دارد و در نهایت می خواهد چکار کند؟ ساعت ها کد را بالا پایین می کنید تا بالاخره میفهمید «آها» و دلیل نهایی آن را می فهمید.

حالا تصور کنید که کد پایین را می بینید:

# The payment gateway sometimes returns a 200 OK with an embedded error message in JSON.
# We parse the body here before the upstream validation so we can extract error codes early.
data = json.loads(response.text)

به یکباره همه چیز روشن می شود: حالا می دانید که چرا این کد اینجا نوشته شده است. این why به شما دقیقا می گوید مساله چیست. این همان تفاوت میان «کامنت‌های چگونه» (توضیح دادن اینکه کد چه می‌کند) و «کامنت‌های چرا» (توضیح دادن منطق و دلیل) است. و در دنیای توسعهٔ نرم‌افزار مدرن، کامنت‌های چرا همیشه برنده‌اند.

کامنت های چگونه هیچ ارزش افزوده ای ایجاد نمی کنند شما باید کدتان آنقدر تمیز باشد که نیازی به کامنت «چگونه» نداشته باشید. برای این کار باید متغیر های با معنا انتخاب کنید و از منطق های پیچیده برای انجام کاری مشخص پرهیز کنید. با این حال چگونه انجام دادن چیزی به شما نمی گوید «چرا» این کار را انجام می دهیم. به صورت مشخص تر کد ها تهی از «نیت» (intention) و «چرایی» هستند. به مثال زیر توجه کنید:

def calculate_settlement_amount(transactions):
    """
    Calculates the final settlement amount.

    Why: 
    - We apply a 3-day rolling average to smooth out FX fluctuations (requested by Finance, Jan 2024).
    - Exclude refunds pending investigation (compliance requirement).
    - Round to 2 decimal places because the downstream ledger rejects more precision.
    """
    # Exclude suspicious refunds
    filtered = [t for t in transactions if not t.pending_investigation]

    # Apply rolling average for FX normalization
    normalized = rolling_average(filtered, days=3)

    # Sum and round
    return round(sum(t.amount for t in normalized), 2)

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

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

# Bit trick: drops the lowest set bit (faster than looping)
x &= x - 1

با این حال چنین مواردی استثنا هستند

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