Formatting block comments

Question

The first style of formatting seems to be much more popular than the second. Why is that?

---

The first (asterisk on every line)

/*
 * line 1
 * line 2
 * line 3
 */

The second (the minimum amount of asterisks)

/*
line 1
line 2
line 3
*/

Answer 1

Probably because it is more readable, in case the comment has a lot of rows you know you are reading a comment even if you do not see the end.

Answer 2

The main reason is because of the PHP Documenters.

Documenters such as PHPDoc are built to parse comment blocks in that form, an example of a parsable comment block is like so:

/**
 * Page-Level DocBlock
 * @package MyPackage
 * @category mycategory
 */

As you can see that the asterisk is on each line and some lines contain an @ symbol, this is what you call a tag denoter, it tells the parser that this line should be processed and file under the category value for the documentation.

Also taking a look at the Zend Coding Standards - Inline Documentation this also states that you should use this type of commenting for such parsers and readability.

Answer 3

It is easier to see where the comment begins and ends.

One need only scan down the left column until the asterisks 'run out' to find the next bit of code.

Where the first method breaks down is when it comes time to rewrite the comments. Now it requires reformatting the lines to make the asterisks line up. That is a no-no unless you have a tool to do that for you automatically.

In McConnell's "Code Complete" (second ed), p 790, he says:

For longer comments, the task of creating long columns of double slashes, manually breaking lines of text between rows, and similar activities is not very rewarding, and so the /* ... */ syntax is more appropriate for multiline comments.

The point is that you should pay attention to how you spend your time. If you spend a lot of time entering and deleting [text] to make [the asterisks] line up, you're not programming; you're wasting time. Find a more efficient style.