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

It is (arguably) more readable or better looking. People have used ASCII art for quite some time, e.g.

/*********************
 * here is the doc   *
 *********************/

or something.

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.

Answer 4

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 5

I like it because it visually differentiates between block-commented out code and documentation.

If I want to comment out a bunch of code, this:

/*
int i;
someCode(i);
print i;
*/

Is much nicer because I can either move the start/end parts to enable part of it, or just delete two lines to enable it all. With the other format I can't do that. As a result, it's nicer for documentation to have the other style because you're never trying to "uncomment" documentation.

Now, with a rich editor I prefer to comment out code using line-comments, but that's another argument.

On line comments for commented-out code

I like this better for commented out code:

//   int i;
//   someCode(i);
//   print i;

There are numerous reasons for this. First, it makes it easy for just one line to be uncommented (enabled). Second, it gives a better visual indication that it's commented out then you get with a block comment (which relies on syntax highlighting, as others have mentioned).

But third, and most importantly, it allows you to safely include block comments in what you're commenting out.

Observe the difference in SO's syntax highlighting when I comment out this:

/**
 * Does something to i and then prints i
 */
public void messWithI() {
    int i;
    someCode(i);
    print i;
}

With block comments:

/*/**
 * Does something to i and then prints i
 */
public void messWithI() {
    int i;
    someCode(i);
    print i;
}*/

With line comments:

//   /**
//    * Does something to i and then prints i
//    */
//   public void messWithI() {
//       int i;
//       someCode(i);
//       print i;
//   } 

The reason you need a rich editor for this is that if you were to apply/remove comments this way manually, it would be a significant number of keystrokes. IDEs have utilities that do this for you (Eclipse is CTRL-/) and advanced text editors have macros or at least vertical selections.

Answer 6

Personally I use // for every comments and keep the /* */ for temporary usages like commenting out many functions while refactoring. Using /* */ for block-comments would prevent me from commenting a lot of code quickly.

So my block comments look like this:

//*****************************
//  Some 
//  Comments
//  Here
//*****************************