[RFC|Rejected] Comments on their own lines (coding guidelines)

[Oleg]

I would like to propose that all comments should be on their own lines.

[EXreaction]

I think that in some cases, comments after the line might be more readable.

For example:

Code: Select all

$array = array(
'foo' => foo', // Some description about foo
'bar' => bar, // Some description about bar
);

Code: Select all

$array = array(
// Some description about foo
'foo' => foo',
// Some description about bar
'bar' => bar,
);

Code: Select all

$array = array(
// Some description about foo
'foo' => foo',

// Some description about bar
'bar' => bar,
);

The middle example could cause issues if the comment is somewhat ambiguous and is between multiple items without extra spacing

[Pony99CA]

Comments describing sections of code should be on their own lines; comments describing a single line should be on that line.

For example, I almost always include block end comments showing the code that started the block:

Code: Select all

if (x == y) {
   do_something;
} else {
   do_something_else;
} // if (x == y) ... else ...

Putting that comment on a separate line would also look odd.

Steve

[MichaelC]

-1 as it makes readability in situations like the one demonstrated by Nathan worse.

[Senky]

-1

[MichaelC]

-1

-1 or +1 means nothing if not explained. Especially if you say -1 please say why.

[drathbun]

Comments describing sections of code should be on their own lines; comments describing a single line should be on that line.

This is my opinion as well. I don't think I've ever coded any other way.

[imkingdavid]

As a rule of thumb, comments always refer to the code directly following them. I do not mind comments at the end of the line, except in the cases where I have to scroll over. If you are simply commenting on a short line of code, I don't mind a comment on the same line, but I would rather not have to scroll over a lot just to read a comment; in those cases, putting it on the line before is much preferable.

Any time a comment spans more than one line, the whole thing should be placed above the code it is referring to, never next to it.

For instance, in the example Pony99CA provided, the comment following the } that was the only thing on that line, that is no problem. But if you have some deeply nested if statements and decide to write a paragraph explaining it, write it above the if, not next to it.

[Senky]

-1

-1 or +1 means nothing if not explained. Especially if you say -1 please say why.

I do not like that idea. EXreaction posted some cases that look really ugly. I have no problem with adding comments on their own lines when you call a method, or assign a variable, but in arrays it should be always on the same line, as well as other cases, when it looks better. If you want to make code more readable by this rule, it should really improve readability - in all cases. Otherwise it should be labeled as recommendation. It is not a problem to request PR sender to move comment on the blank line...

[callumacrae]

As a rule of thumb, comments always refer to the code directly following them. I do not mind comments at the end of the line, except in the cases where I have to scroll over. If you are simply commenting on a short line of code, I don't mind a comment on the same line, but I would rather not have to scroll over a lot just to read a comment; in those cases, putting it on the line before is much preferable.

I think most of us code so that comments can be read in a 79 character wide window anyway.