what is the purpose of the extra asterisks in php

Question

I've (finally) been reading up on PEAR (php) coding standards.

What is the purpose of commenting like this:

/** 
*   Here is my comment
*   I Wrote this in a haiku
*   But why put the stars?
*/

As opposed to this:

/* 
   Here is a comment
   No haiku or 
   anything special, but it still works!
*/

Answer 1

If you use the excellent free text editor jEdit for editing your PHP it highlights the code in different colours to show what is a verb, what is a variable etc.

If you comment out a block with /* ... */ everything inside the block goes orange, making it difficult to read the code.

If you instead comment it out with /** ... */ then it changes everything in the block to a different set of colours that still highlight the different parts of the code, meaning the code remains very readable.

PS. If you use Notepad or similar to edit your PHP code then I strongly suggest that you get jEdit. It will save you a huge amount of time and frustration. Things like automatically indicating the start and end of { } , ( ) etc.

Answer 2

The double asterisk comment is used sometime by certain documentation systems. The documentation system will proccess the block and look for certain keywords like @author or @var.

Single asterisk comments wil be treated as // comments.

See PhpDoc http://www.phpdoc.org/docs/latest/guides/types.html

Answer 3

The /** stuff */ document is also referred to as DocBlock notation.

It's used to document PHP functions, classes, etc.

/** 
* A test function
*
* @param  foo $bar
* @return baz
*/
function test(foo $bar) { return new baz; }

Some editors make good use of this to perform their Code Insight feature, a very powerful tool that reduces the time you have to spend looking at your old function declarations. Aptana and Zend Studio have this feature, probably others as well.

You can also use it in combination with Reflection to do some sort of AOP, doing runtime inspection of the DocBlock above your declarations. In fact, Doctrine uses it to build an object attribute map for their "Active Record" implementation.

Answer 4

Readability.

It clearly highlights the commented section to people reading the code.

Answer 5

I agree with ajon and Quentin. Mainly it's readability. However,there is one more thing.

There are automatic documentation generators (like doxygen ).

They require some particular comment formatting to include these comments into documentation. I believe this style of commenting is used exactly for this purpose (look at following doxygen documentation page - http://www.stack.nl/~dimitri/doxygen/docblocks.html)

Answer 6

I think it is mostly just for appearance/readability. Imagine you have a very long comment section that extends beyond one screen. Then seeing those asterisks lets you know it is part of a comment even if you can't see the beginning and end.