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

آموزش برنامه نویسی, آموزش برنامه نویسی php

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

می 15, 2025

کامنت (توضیح)

در هر برنامه کامپیوتری (مانند برنامه PHP) متنی توضیحی است که توسط کامپایلر یا مفسر زبان نادیده گرفته می‌شود. هدف آن کمک به کاربر برای درک منطق استفاده شده در الگوریتم برنامه است.

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

کامنت‌های تک‌خطی

کامنت تک‌خطی با استفاده از “#”
کامنت تک‌خطی با استفاده از “//”
کامنت‌های چندخطی
کامنت‌های DocBlock (برای مستندسازی)

کامنت‌های تک‌خطی در PHP

این نوع کامنت‌ها معمولاً برای توضیحات کوتاه یا یادداشت‌های مرتبط با کد محلی استفاده می‌شوند. PHP دو علامت برای درج کامنت تک‌خطی در برنامه دارد.

کامنت تک‌خطی با استفاده از “#”

خطی در کد PHP که با علامت “#” شروع شود به عنوان کامنت تک‌خطی در نظر گرفته می‌شود.

<?php

# Single line comment starting with # symbol

echo 'Hello World';

<?php # Single line comment starting with # symbol echo 'Hello World'; ?>

<?php
   # Single line comment starting with # symbol
   echo 'Hello World';
?>

کامنت‌های تک‌خطی با استفاده از “//”

PHP همچنین از سبک کامنت تک‌خطی زبان C با علامت “//” پشتیبانی می‌کند. خطی که با دو علامت مورب (//) شروع شود به عنوان کامنت در نظر گرفته می‌شود.

<?php

// Single line comment starting with // symbol

echo 'Hello World';

<?php // Single line comment starting with // symbol echo 'Hello World'; ?>

<?php
   // Single line comment starting with // symbol
   echo 'Hello World';
?>

کامنتی که با علامت “#” یا “//” شروع شود نیازی به بسته شدن ندارد. تأثیر این علامت‌ها تا پایان خط فیزیکی ادامه دارد.

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

کامنت‌های چندخطی در PHP

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

روش نوشتن کامنت چندخطی در PHP همانند زبان C است. یک یا چند خط که بین علامت‌های “/” و “/” قرار گیرند، به عنوان کامنت در نظر گرفته می‌شوند.

مثال کامنت چندخطی

در PHP در اینجا مثالی از کامنت چندخطی آمده است.

<?php

/* This is a multiline comment example

program to add two numbers

Variables used - $x for first number,

$y for second number */

$x=10;

$y=20;

print "Total = ". $x+$y;

<?php /* This is a multiline comment example program to add two numbers Variables used - $x for first number, $y for second number */ $x=10; $y=20; print "Total = ". $x+$y; ?>

<?php

   /* This is a multiline comment example
   program to add two numbers
   Variables used - $x for first number, 
   $y for second number */
   
   $x=10;
   $y=20;
   print "Total = ". $x+$y;
?>

توجه داشته باشید که حتی می‌توانید یک خط را هم داخل علامت‌های “/* .. /” قرار دهید. اما اگر در برنامه علامت “/” وجود داشته باشد، حتماً باید علامت پایان کامنت “*/” داشته باشد. در غیر این صورت، خطایی به شکل زیر نمایش داده می‌شود

PHP Parse error: Unterminated comment starting line 3 in /home/cg/root/65ded9eeb52fc/main.php on line 3

PHP Parse error:  Unterminated comment starting line 3 in /home/cg/root/65ded9eeb52fc/main.php on line 3

کامنت DocBlock در PHP (برای مستندسازی)

کامنت «DocBlock» نوعی از کامنت کد است که معمولاً با “/” شروع شده و در هر خط از ستاره () استفاده می‌کند تا مستندات دقیقی درباره یک بخش خاص از کد مانند تابع، کلاس یا متغیر ارائه دهد. این نوع کامنت به توسعه‌دهندگان کمک می‌کند تا به راحتی مفهوم و نحوه استفاده از آن بخش کد را درک کنند؛ و معمولاً همراه با ابزارهایی به کار می‌رود که به صورت خودکار مستندات API را تولید می‌کنند.

در ادامه، نمونه‌ای از کامنت DocBlock آورده شده است.

/**

* This function adds two numbers.

* @param int $a First number

* @param int $b Second number

* @return int Sum of $a and $b

function add($a, $b) {

return $a + $b;

}

/** * This function adds two numbers. * * @param int $a First number * @param int $b Second number * @return int Sum of $a and $b */ function add($a, $b) { return $a + $b; }

/**
 * This function adds two numbers.
 *
 * @param int $a First number
 * @param int $b Second number
 * @return int Sum of $a and $b
 */
function add($a, $b) {
    return $a + $b;
}

نکات مفید برای نوشتن کامنت‌ها

همیشه کامنت‌ها را برای دیگران بنویسید، نه برای خودتان، چون فرض کنید برنامه‌نویس دیگری قرار است کد شما را بخواند.
از زبان انگلیسی صحیح و دستور زبان درست استفاده کنید و از به‌کار بردن اختصارات، اشتباهات املایی یا کلمات مبهم خودداری کنید. زیرا کامنت‌های خوب نوشته شده، خوانایی کد را بهبود می‌بخشند.
درباره موارد واضح و روشن کامنت نگذارید؛ اگر کد خودگو و قابل فهم است، کامنت اضافی لازم نیست.
می‌توانید بخش‌هایی از کد که نیاز به بهبود یا اشکال‌زدایی دارند را علامت بزنید.
کامنت‌ها را بالای بلوک کدی که به آن اشاره دارند قرار دهید.
هر زمان کد تغییر کرد، کامنت‌ها را نیز به‌روزرسانی کنید.
اگر تابعی منطق پیچیده‌ای دارد، بهتر است با استفاده از کامنت‌های چندخطی (Block Comments) آن را به صورت دقیق توضیح دهید.
همیشه برای توابع و کلاس‌ها از کامنت‌های DocBlock استفاده کنید.