Formatting block comments

Question

The first formatting style seems much more popular than the second. Why is this?

---

First (asterisk on each line)

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

Second (minimum number of stars)

 /* line 1 line 2 line 3 */ 

Answer 1

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

Answer 2

The main reason is related to PHP Documenters.

Documentators such as PHPDoc are built to parse comment blocks in this form, an example parsing block looks like this:

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

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

Also, by looking at the Zend Coding Standards - Inline Documentation , it is also said that you should use this type of comment for such parsers and for readability.

Answer 3

It’s easier to see where the comment begins and ends.

You only need to scan the left column until the stars come out to find the next bit of code.

Where the first method breaks when it's time to rewrite comments. Now this requires reformatting the strings to display the asterisks. This is a no-no if you do not have a tool to do this automatically.

In McConnell's "Code Complete" (Second Edition), p. 790, he says:

For longer comments, the task of creating long columns of double slashes, manually breaking lines between lines and similar actions is not very useful, so the syntax / * ... * / is more suitable for multi-line comments.

The fact is that you should pay attention to how you spend time. If you spend a lot of time typing and deleting [text] to make stars, you are not programming; you are wasting time. Find a more effective style.

Answer 4

Personally, I use // for each comment and save /* */ for temporary use, for example, commenting on many functions when refactoring. Using /* */ for block comments will not allow me to quickly comment on the code.

So my block comments are as follows:

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

Answer 5

It is (possibly) more readable or better looking. People have long been using ASCII art, for example.

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

or something like that.

Answer 6

I like it because it visually distinguishes the code with comments and documentation.

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

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

This is much nicer, because I can either move the start / end part to include part of it, or simply delete two lines to include everything. In a different format, I cannot do this. As a result, it’s better to use a different style for documentation, because you never try to “uncomment” the documentation.

Now, with a rich editor, I prefer to comment on the code using line comments, but this is another argument.

Comments on the line for the code with comments

I like this better for commented code:

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

There are many reasons for this. Firstly, it makes it easier for one line to be uncommented (included). Secondly, it gives a better visual indication of what it has commented out, and then you get a block comment (which relies on syntax highlighting, as others have mentioned).

But thirdly, and most importantly, it allows you to safely include block comments in what you are commenting on.

Observe the difference in SO syntax highlighting when I comment on 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 comments on the line:

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

The reason you need a rich editor is that if you manually or manually delete comments, it will be a significant number of keystrokes. The IDE has utilities that do this for you (Eclipse is CTRL - / ), and advanced text editors have macros or at least vertical options.