[RFC & Patch][Implemented] Coding Guidelines

Note: We are moving the topics of this forum and it will be deleted at some point

Publish your own request for comments/change or patches for the next version of phpBB. Discuss the contributions and proposals of others. Upcoming releases are 3.2/Rhea and 3.3.
User avatar
bantu
3.0 Release Manager
3.0 Release Manager
Posts: 557
Joined: Thu Sep 07, 2006 11:22 am
Location: Karlsruhe, Germany
Contact:

Re: [RFC & Patch] Coding Guidelines

Post by bantu »

bantu wrote:I'd like to suggest to add a rule that the last line of a text file should end with "\n".

Example

Changing

Code: Select all

..."\n"
$someVar = false; 
to

Code: Select all

..."\n"
$someVar = false;"\n"
$someOtherVar = false; 
will list the $someVar-Line as modified in the repository, which should not be.

It should be

Code: Select all

..."\n"
$someVar = false;"\n" 
from the beginning, so you can easily add

Code: Select all

$someOtherVar = false;"\n" 
For the same reason

Code: Select all

array(
    'key1'    => 'value1',
    'key2'    => 'value2'
) 
should always be written as

Code: Select all

array(
    'key1'    => 'value1',
    'key2'    => 'value2',
) 
Note the comma on the last line in the array.

___

On a side note

Code: Select all

array('key1' => 'value1', 'key2' => 'value2',); 
should probably always be written as

Code: Select all

array('key1' => 'value1', 'key2' => 'value2'); 
as a convention (without a real reason, maybe for readability).
User avatar
Erik Frèrejean
Registered User
Posts: 207
Joined: Thu Oct 25, 2007 2:25 pm
Location: surfnet
Contact:

Re: [RFC & Patch] Coding Guidelines

Post by Erik Frèrejean »

bantu wrote:For the same reason

Code: Select all

array(
    'key1'    => 'value1',
    'key2'    => 'value2'
) 
should always be written as

Code: Select all

array(
    'key1'    => 'value1',
    'key2'    => 'value2',
) 
Note the comma on the last line in the array.
I'm really in favor of this, I've found it always annoying++ that not all arrays in phpBB have a comma at the last entry. Makes it annoying to add stuff to the array.
Available on .com
Support Toolkit developer
Michaelo
Registered User
Posts: 106
Joined: Thu Apr 01, 2004 7:56 am
Location: Dublin

Re: [RFC & Patch][Implemented] Coding Guidelines

Post by Michaelo »

One other advantage... simplifies search updates...
Always better to use Search > Add, after as opposed to search, in-line find, in-line add after etc... and all for a comma!
Mods: Forum Icons Enhancement, Kiss Portal Engine
Links:
Kiss Portal Engine (dev site) Stargate Portal (archive site) ...
Styles: Technika
User avatar
bantu
3.0 Release Manager
3.0 Release Manager
Posts: 557
Joined: Thu Sep 07, 2006 11:22 am
Location: Karlsruhe, Germany
Contact:

Re: [RFC & Patch][Implemented] Coding Guidelines

Post by bantu »

Michaelo wrote:One other advantage... simplifies search updates...
Always better to use Search > Add, after as opposed to search, in-line find, in-line add after etc... and all for a comma!
That's not a valid point as we want to get rid of this whole core-edit thing.
Michaelo
Registered User
Posts: 106
Joined: Thu Apr 01, 2004 7:56 am
Location: Dublin

Re: [RFC & Patch][Implemented] Coding Guidelines

Post by Michaelo »

True in relation to manual editing... but assuming the core may require additional elements to be added during normal updating, the comma will still make it easier...
Mods: Forum Icons Enhancement, Kiss Portal Engine
Links:
Kiss Portal Engine (dev site) Stargate Portal (archive site) ...
Styles: Technika
User avatar
callumacrae
Former Team Member
Posts: 1046
Joined: Tue Apr 27, 2010 9:37 am
Location: England
Contact:

Re: [RFC & Patch][Implemented] Coding Guidelines

Post by callumacrae »

This one is a bit of a holy war, but we're going to use a style that can be summed up in one sentence: Braces always go on their own line.
Needs to be changed to:
This one is a bit of a holy war, but we're going to use a style that can be summed up in one [s]sentence[/s]paragraph:

Braces always go on their own line, with several major exceptions when writing JavaScript. When returning an object, you should obviously have braces on the same line, as due to JavaScript's implied semicolon insertion mechanism, the following code is invalid:

Code: Select all

function func() {
    return
    {
        foo: "bar"
    };
}
In that example, the function would return "undefined". For this reason, you should have the braces on the same line when returning objects. You should also have braces on the same line when defining variables as objects, as while it is still valid, it is difficult to read.

When defining anonymous functions, you should have braces on the same line, or the code is difficult to read. However, you should still have the braces on their own line when defining functions traditionally (function funcName()).

Seriously though - while I can understand that where to have braces in PHP is purely a matter of personal preference - depending on what you're used to, either look good - in a language such as JavaScript, it simply does not work to have braces on their own line. It can result in code like the following:

Code: Select all

/**
 * Returns a random function.
 * 
 * @constructor
 */
function MyFunc(a)
{
	var i = 0;
	if (a)
	{
		return function() {
			return {
				i: i += 1
			}
		}
	}
	else
	{
		return function() {
			return {
				i: i += 2
			}
		}
	}
}
The code doesn't do much, but you can that it looks fairly inconsistent and stupid compared to how I would write it:

Code: Select all

/**
 * Returns a random function.
 * 
 * @constructor
 */
function MyFunc(a) {
	var i = 0;
	if (a) {
		return function() {
			return {
				i: i += 1
			}
		}
	} else {
		return function() {
			return {
				i: i += 2
			}
		}
	}
}

So I think that all JavaScript contained in the phpBB package should have the braces on the same line. However, as having JavaScript and PHP using different coding standards would be confusing and where the braces are in PHP are purely down to personal preference, I think that the entire phpBB project should switch to having braces on the same line.

In summary:

Advantages to having braces on same line:
- Doesn't look stupid, and is more consistent.
- It's usually more widely used, so developers will be more likely to be used to it.

Advantages to having braces on own line:
- No change, so nothing would need to be changed. However, as phpBB would be having a full rewrite, this doesn't seem like a major problem.
- Symfony has the braces on own line.



I would also suggest an amendment to the Method & Function Names section; functions, when used a constructor in a Javascript, should start with a capital letter.
Made by developers, for developers!
My blog
Post Reply