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

These RFCs were either rejected or have been replaced by an alternative proposal. They will not be included in phpBB.
Oleg
Posts: 1150
Joined: Tue Feb 23, 2010 2:38 am
Contact:

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

Post by Oleg »

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

User avatar
EXreaction
Registered User
Posts: 1555
Joined: Sat Sep 10, 2005 2:15 am

Re: [RFC] Comments on their own lines (coding guidelines)

Post by 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

User avatar
Pony99CA
Registered User
Posts: 986
Joined: Sun Feb 08, 2009 2:35 am
Location: Hollister, CA
Contact:

Re: [RFC] Comments on their own lines (coding guidelines)

Post by 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
Silicon Valley Pocket PC (http://www.svpocketpc.com)
Creator of manage_bots and spoof_user (ask me)
Need hosting for a small forum with full cPanel & MySQL access? Contact me or PM me.

User avatar
MichaelC
Development Team
Development Team
Posts: 889
Joined: Thu Jan 28, 2010 6:29 pm

Re: [RFC] Comments on their own lines (coding guidelines)

Post by MichaelC »

-1 as it makes readability in situations like the one demonstrated by Nathan worse.
Formerly known as Unknown Bliss
psoTFX wrote: I went with Olympus because as I said to the teams ... "It's been one hell of a hill to climb"
No unsolicited PMs please except for quotes.


User avatar
MichaelC
Development Team
Development Team
Posts: 889
Joined: Thu Jan 28, 2010 6:29 pm

Re: [RFC] Comments on their own lines (coding guidelines)

Post by MichaelC »

Senky wrote:-1
-1 or +1 means nothing if not explained. Especially if you say -1 please say why.
Formerly known as Unknown Bliss
psoTFX wrote: I went with Olympus because as I said to the teams ... "It's been one hell of a hill to climb"
No unsolicited PMs please except for quotes.

drathbun
Registered User
Posts: 72
Joined: Wed Feb 15, 2006 6:40 pm
Location: Texas
Contact:

Re: [RFC] Comments on their own lines (coding guidelines)

Post by drathbun »

Pony99CA wrote: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.
Sometimes you're the windshield, sometimes you're the bug.

User avatar
imkingdavid
Registered User
Posts: 1050
Joined: Thu Jul 30, 2009 12:06 pm

Re: [RFC] Comments on their own lines (coding guidelines)

Post by 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.
I do custom MODs. PM for a quote!
View My: MODs | Portfolio
Please do NOT contact for support via PM or email.
Remember, the enemy's gate is down.

Senky
Extension Customisations
Extension Customisations
Posts: 315
Joined: Thu Jul 16, 2009 4:41 pm

Re: [RFC] Comments on their own lines (coding guidelines)

Post by Senky »

Unknown Bliss wrote:
Senky wrote:-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...

User avatar
callumacrae
Former Team Member
Posts: 1046
Joined: Tue Apr 27, 2010 9:37 am
Location: England
Contact:

Re: [RFC] Comments on their own lines (coding guidelines)

Post by callumacrae »

imkingdavid wrote: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.
Made by developers, for developers!
My blog

Post Reply