آموزش کامنت‌گذاری در PHP بر اساس استاندارد گوگل و Clean Code

مقدمه؛ چرا کامنت‌گذاری اصولی در PHP اهمیت دارد؟

بسیاری از برنامه‌نویسان فکر می‌کنند کامنت‌گذاری فقط نوشتن چند خط توضیح ساده بالای کدها است. اما بر اساس استانداردهای مهندسی نرم‌افزار گوگل، کامنت‌ها باید چراایی (Why) اجرای یک کد را توضیح دهند، نه چگونگی (How) آن را. کدی که خوب نوشته شده باشد، خودش چگونگی کارکردش را نشان می‌دهد؛ بنابراین کامنت‌ها باید اطلاعات ارزشمندی را ارائه دهند که از خود کد قابل برداشت نیست.

انواع کامنت‌گذاری در PHP

در زبان PHP به طور کلی از سه روش برای ایجاد کامنت استفاده می‌شود:

• کامنت‌های یک‌خطی (Single-line): با استفاده از //
• کامنت‌های چندخطی (Multi-line): با استفاده از /* ... */
• بلاک‌های مستندسازی (DocBlocks): با استفاده از /** ... */

توجه داشته باشید که استفاده از علامت هش # برای کامنت‌گذاری تک‌خطی در PHP مجاز است، اما در استانداردهای مدرن و گوگل، استفاده از // به شدت ترجیح داده می‌شود.

اصول کلیدی کامنت‌گذاری بر اساس استانداردهای گوگل

۱. کامنت‌های بدیهی را حذف کنید

گوگل تأکید دارد که نباید خطوط واضح کد را مجدداً با زبان عامیانه تکرار کرد. این کار فقط باعث شلوغی و کاهش خوانایی کد می‌شود.

< ? p h p 

// BAD: این کامنت کاملاً بیهوده است!
$userCount = 0; // مقداردهی اولیه متغیر تعداد کاربران به صفر

// GOOD: کامنت توضیح می‌دهد که چرا این مقدار اولیه انتخاب شده است
// We start at -1 because the main server's response code starts indexing from zero.
$statusIndex = -1;

? >

۲. استاندارد نوشتن کامنت‌های TODO

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

< ? p h p

// TODO(alireza): بهینه‌سازی کوئری دیتابیس برای جلوگیری از سربار حافظه در رکوردهای بالا
$results = $db--->fetchAll("SELECT * FROM large_table");
? > 

۳. مستندسازی متدها و کلاس‌ها با PHPDoc

برای متدها و توابعی که ورودی و خروجی‌های متعددی دارند، باید از بلاک‌های استاندارد PHPDoc استفاده کنید. این کار به ویرایشگرها (مانند VS Code یا PHPStorm) کمک می‌کند تا نوع داده‌ها (Type Hinting) را بهتر تشخیص دهند.

< ? p h p

/**
 * Calculates the total price including dynamic tax.
 *
 * @param float $price The base price of the item.
 * @param float $taxRate The tax percentage (e.g., 0.09 for 9%).
 * @return float The calculated final price.
 * @throws InvalidArgumentException If price is negative.
 */
function calculateTotalPrice(float $price, float $taxRate): float
{
    if ($price < 0) {
        throw new InvalidArgumentException("Price cannot be negative.");
    }
    return $price + ($price * $taxRate);
}
? > 

قوانین طلایی برای نوشتن کامنت‌های پاک (Clean Code)

1. به‌روز نگه‌داشتن کامنت‌ها: اگر کدی را تغییر دادید، حتماً کامنت‌های مربوط به آن را نیز به‌روزرسانی کنید. کامنت قدیمی و نادرست از بی‌کامنت بودن بدتر است.
2. استفاده از گرامر و املای صحیح: کامنت‌ها باید ساختار جمله‌ای مرتب داشته باشند و با حروف بزرگ شروع شده و به نقطه ختم شوند (به‌خصوص در زبان انگلیسی).
3. پرهیز از کدهای کامنت شده: هرگز کدهای قدیمی یا استفاده نشده را کامنت نکنید تا در آینده استفاده کنید؛ برای این کار از سیستم‌های کنترل نسخه مثل Git استفاده کنید. کدهای کامنت‌شده پروژه را کثیف می‌کنند.

نتیجه‌گیری

رعایت استانداردهای گوگل در کامنت‌نویسی PHP باعث می‌شود که کدهای شما به یک مستند زنده تبدیل شوند. کار تیمی روان‌تر شده و فرآیند نگهداری و توسعه نرم‌افزار با سرعت و دقت بسیار بیشتری انجام می‌گیرد. تلاش کنید از امروز اصول PHPDoc و کامنت‌های متمرکز بر «چرا» را در پروژه‌های خود پیاده‌سازی کنید.

پیشنمایش