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

Question

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
\*

Answer 1

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

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

or

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

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.