خوب، اصل مطلب، بدون هیچ حاشیه ای و فکر کردن روی چه طور شروع کنم نوشتن این یکی رو؟

معمولا ما برنامه نویس ها اونقدر حوصله نداریم که کدمون رو درست کامنت بگذاریم، ولی وقتی application جدی بشه ، کامنت گذاری یک بخش جدایی ناپذیر از application میشه.دلایلش خیلی روشنه و این بخش رو می پرونیم.اما نکته مهم تر(به نظر من) اینکه شور قضیه هم درنیاد.مثلا کد زیر یک جورایی کامنت اضافه و حشو حساب میشه و بهتر این جور چیزها از روی اسم متغیر مشخص باشه که داخل کد زیر هم هست.در حقیقت کامنت ها به ما بفهمونند که چرا داریم این کارو می کنیم ، اینکه چطور رو می شه در خود کد فهمید(البته جاهای سخت که با یک نگاه نمی شه فهمید رو باید کامنت گذاشت تا علاوه بر Why به How هم از داخل کامنت مشخص شه)

$host="localhost";//hostname

// توجه:قسمت بالا تجربیات خودم بود و نحوه ای که دوست دارم، هیچ لزومی وجود نداره همه مثل هم فکر کنیم، شما می تونید واسه هر خط کدتون ۱۰ خط کامنت بگذارید.

بهترین روش برای کامنت گذاشتن در PHP استفاده از استاندارد PHPDoc ه، در حقیقت خود PHPDoc یک اقتباس از JavaCode هست.استفاده از استاندارد PHPDoc دو مزیت داره،

1. می تونید از روی کامنت هاتون document بسازید.
   برای اینکار اول phpdoc رو نصب می کنید.

$ pear channel-discover pear.phpdoc.org
$ pear install phpdoc/phpDocumentor

و بعد از اون برای کدهای موجود در شاخه جاری، در پوشه docs یک document بسازید.

$ phpdoc -d . -t docs

۲)IDE ها مفهوم کامنت هارو می فهمند و به شما و دیگران در autocomplete ، آوردن document موقع استفاده و … کمک می کنند.

برای کامنت گذاری با استاندارد PHPDoc در NetBeans

1. کامنت ها با /** شروع می شه  ولی با */ بسته میشه.
2. در netbeans بالای هر تابع اگر /** رو بنویسید و enter بزنید ، خود netbeans براتون بخشی از کامنت رو درست می کنه، پارامترهای ورودی و چیزی که تابع بر می گردونه.
3. در حقیقت هر block از PHPDoc از سه بخش تشکیل میشه، شرح کوتاه(تک خطی)،شرح بلند(هر چقدر بخواهید) و کلمات کلیدی. می تونید از شرح کوتاه یا بلند کدتون از بعضی از دستورات html استفاده کنید تا PHPDoc موقع ساخت document دقیقا از اونها استفاده کنه.شما می تونید از
   

   <b>,<code>,<br>,<i>,<kbd>,<li>,<ol>,<ul>,<p>,<pre>,<samp>,<var>

   استفاده کنید.

4. کلمات کلیدی در PHPDoc همه تک کلمه هستند و با @ شروع می شند.
   میشه کلمات کلیدی PHPDoc رو به چندبخش تقسیم کرد،

• Data Type Tags
  param@ که برای پارامترهای ورودی متد و function ها استفاده میشه
  return@ که نوع چیزی که برگردونده میشه رو مشخص می کنه
  var@ که برای مشخص کردن نوع متغیرهای کلاس ویا ثابت ها به کار میره 
• Legal Tags
  author@ و copyright@ و license@ که کاملا مشخصه
• Versioning Tags
  مثل version@ و since@ و deprecated@
• و بقیشون مثل
  example@ و link@ و see@ و uses@ و package@ و subpackage@

نکته قشنگ اینکه اگه از یه IDE خوشگل مثل Netbeans استفاده کنید(مثل الان خودم) می تونید از تگ todo@ هم استفاده کنید که استاندارد نیست، ولی با Ctrl+6 لیست تمام جاهارو براتون بیاره که قراره انجام بدید.برای استفاده از todo در یک خط هم از //TODO استفاده می شه کرد.