Emanuil Rusev
Emanuil Rusev

Reputation: 35265

Formatting block comments

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

Upvotes: 4

Views: 7602

Answers (7)

Marc Wilson
Marc Wilson

Reputation: 1

I wrote a tool to generate my comments. It lets me enter as many lines as I want. It will use the actual line drawing ascii, if the editor allows, and lets me select centered, double lined outline, what the leading comment string should be, etc. I also have the option to start one line with my comment start character, type as many lines as I like, highlight from the end up to somewhere on the first line of text, hit a key, and it all goes into a nice blocked comment. You can type a comment, hit a key and the line is automatically boxed for you. Of course you need to be using a full font that's monospaced, like Consolas.

'========>     ╔═══════════════════════════════════╗
'========>     ║                                   ║
'========>     ║         This is a sample          ║
'========>     ║          multiline text           ║
'========>     ║ with added buffer above adn below ║
'========>     ║                                   ║
'========>     ╚═══════════════════════════════════╝


;┌──────────────────────────────────┐
;│ Custom array join with delimiter │
;└──────────────────────────────────┘

Upvotes: -2

pcantin
pcantin

Reputation: 554

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

Upvotes: 2

Mark Peters
Mark Peters

Reputation: 81114

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.

Upvotes: 0

RobertPitt
RobertPitt

Reputation: 57268

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.

Upvotes: 4

BryanH
BryanH

Reputation: 6062

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.

Upvotes: 2

musiKk
musiKk

Reputation: 15189

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.

Upvotes: 0

GôTô
GôTô

Reputation: 8053

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.

Upvotes: 10

Related Questions