What are The Valid & Readable approaches to Commenting in PHP5?

In the past 2 months that I have been learning PHP, I have identified more than two styles people use to comment code! I haven't seen much consistency... which I think usually means artists at work. So I wondered: what are the valid ways to comment which are still readable/practical? Seeing all the valid possibilities in 1 place side by side will provide the overview that I am looking for to improve commenting

/*
|  This is what I now use (5chars/3lines) I name it star*wars
\*

Quoting the Manual on Comments:

PHP supports 'C', 'C++' and Unix shell-style (Perl style) comments. For example:

<?php
    echo 'This is a test'; // This is a one-line c++ style comment
    /* This is a multi line comment
       yet another line of comment */
    echo 'This is yet another test';
    echo 'One Final Test'; # This is a one-line shell-style comment
?>

In general, you will want to avoid using comments in your sourcecode. To quote Martin Fowler:

When you feel the need to write a comment, first try to refactor the code so that any comment becomes superfluous.

which means something like

// check if date is in Summer period
if ($date->after(DATE::SUMMER_START) && $date->before(DATE::SUMMER_END)) {

should be rewritten to

if ($date->isInSummerPeriod()) { …

Another comment type you will sometimes encounter is the separator comment, e.g. something like

// --------------------------------------------

################################################

Those are usually indicative that the code they are used in is doing too much. If you find this in a class, check the responsibility of the class and see if some parts of it are better refactored into a standalone class.

As for API docs, the common notation is PHPDoc, e.g.

/**
 * Short Desc
 *
 * Long Desc
 * 
 * @param  type $name description
 * @return type       description
 */
 public function methodName($name) { …

I would argue that you can omit Short and Long Desc if the remaining method signature clearly communicates what it does. However, that requires a certain discipline and knowledge in how to actually write Clean Code. For instance, the following is totally superfluous:

/**
 * Get the timestamp property
 *
 * The method returns the {@link $timestamp} property as an integer.
 * 
 * @return integer the timestamp
 */
 public function getTimestamp() { …

and should be shortened to

/**
 * @return integer
 */
 public function getTimestamp() { …

Needless to say, whether you go for full API docs or not also depends on the project. I'd expect any framework I can download and use to have full API docs. The important thing is just that whatever you decide to do, do it consistently.

You should definitely use the phpdoc standards. Here's a quick start for beginners.

I'm sure you've seen comments like this:

/**
 * example of basic @param usage
 * @param bool $baz 
 * @return mixed 
 */
function function1($baz)
{
   if ($baz)
   {
      $a = 5;
   } else
   {
      $a = array(1,4);
   }
   return $a;
}

Commenting this way makes it not only easy for most PHP-developers to read, but you can also generate nice documentations.

To me every one of them looks equally readable.
I am using both one-liners and multi-line comments as well.

Being highlighted in gray, they are always visible and distinct from other code.
I've seen not a single problem with comments readability before

It's quite common to use phpdoc guidelines for commenting. This includes annotations for generating a documentation.

来源：https://stackoverflow.com/questions/5618592/what-are-the-valid-readable-approaches-to-commenting-in-php5