在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, eg 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 , eg

/**
 * 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.

Answer 2

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.

Answer 3

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

Answer 4

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