[RFC & Patch][Implemented] Coding Guidelines

[naderman]

That sounds very reasonable.

[ToonArmy]

I don't like the CamelCase (instead of camel_case). The variable without camel-case looks a lot cleaner to me.

Code: Select all

$my_var
$myVar

The underscore key is so inconveniently located for programming; shift and letter is much easier to type, personally.

[naderman]

I still wanted to say something about the curly braces that have been discussed previously:

the 2 things that irritate me about the phpbb coding style are:
-- the insistence of having a { and } even for a single statements, e.g. after "if", "while" etc.
-- giving the opening "{" its own line.

these two decisions were made originally "to improve readability", but it is a well established fact that in reality they reduce readability.
maybe the best evidence is python, which very few will deny is *more* readable than either C or perl, while doing away with "{" and "}" altogether.
"{" and "}" are "syntactical sugar" that meant to make the compiler's life easier, but help humans very little.
indentation is sacred and should be observed at all costs, but "{" and "}" are pure noise, as far as readability is concerned, and only serve to distract the reader (at least *this* code reader) from what's important: the content of the statements rather than their bracketing.

There is one reason in particular why always wrapping code in curly braces is a good idea: You will never accidentally add an unconditional statement that was meant to be conditional, because you need to add braces once you want to add a second statement inside the if. And as for the other part of your argument PHP has curly braces, we can't just "do away" with them, so we can as well use them consistently. Giving "{" its own line is really mostly an arbitrary choice, although I think it does improve readability, but just as well would a requirement for empty lines before and after long statement lists. I do not think it hinders readability however.

[onehundredandtwo]

Will this also apply for the database, or just the scripts?

I like underscores because to me it's a lot easier to read. I'm not sure if it's the same for other people, but that's the way I've always written PHP.

[naderman]

I have intentionally left out anything related to the database since we don't even know how we are going to access databases yet.

If nobody has any big objections by the end of the day (wednesday 20th of january) I'll merge this into phpbb master.

[nickvergessen]

{ } also may be much easier for MODs to add code into the sections.
else they would need to add the braces and might collate harder on updates.

[naderman]

We do want to get rid of any MODs changing code though

[Highway of Life]

The tabs versus spaces argument may be an eternal religious war. I’m not sure if it’s possible to come to an absolute agreement since most of the developers that I know are either adamantly opposed to spaces, or adamantly opposed to tabs. (Although most developers I know use/prefer tabs to spaces).

This is the issue for me and the reason why I highly prefer tabs to spaces.

1. When writing code, I find it easier to line things up (such as arrays) if you use tabs, I find myself spending more time editing if I have to work with spaces. (A company I worked for required spaces instead of tabs)
2. All decent code editors have the ability to set the tab width, however spaces are spaces and cannot be adjusted for readability. (Unless you have an 'entab', 'detab' editor which can convert spaces<=>tabs).
3. I have found with phpBB, the code/mod authors who are the ones sending code with spaces instead of tabs are generally those who are very new at coding. (It's a generalization). So if the reason to switch from tabs to spaces is based on the fact that people regularly send code using spaces instead of tabs, why? - Doesn't it make more sense to accommodate the more heavy-duty, high-output coders rather than the hobby programmer when it comes to code formatting?
   There is an interesting paper on this by Steve McConnel:

   In their classic paper Perception in Chess, Chase and Simon reported on a study that compared the abilities of experts and novices to remember the positions of pieces in chess. When pieces were arranged on the board as they might be during a game, the experts' memories were far superior to the novices'. When the pieces were arranged randomly, there was little difference between the memories of the experts and the novices. The traditional interpretation of this result is that an expert's memory is not inherently better than a novice's but that the expert has a knowledge structure that helps him or her remember particular kinds of information. When new information corresponds to the knowledge structure -- in this case, the sensible placement of chess pieces -- the expert can remember it easily. When new information doesn't correspond to a knowledge structure -- the chess pieces are randomly positioned -- the expert can't remember it any better than the novice.
   
   A few years later, Ben Shneiderman duplicated Chase and Simon's results in the computer-programming arena and reported his results in a paper called Exploratory Experiments in Programmer Behavior. Shneiderman found that when program statements were arranged in a sensible order, experts were able to remember them better than novices. When statements were shuffled, the experts' superiority was reduced. Shneiderman's results have been confirmed in other studies. The basic concept has also been confirmed in the games Go and bridge and in electronics, music, and physics.

4. As Jeff Atwood put it...

   Choose tabs, choose spaces, choose whatever layout conventions make sense to you and your team. It doesn't actually matter which coding styles you pick. What does matter is that you, and everyone else on your team, sticks with those conventions and uses them consistently.

   Do we really need to switch our layout conventions from what everyone has gotten used to in phpBB3, something as fundamental as spaces and tabs which is at the heart of the hard-core developers style, and change that to something completely different?

[Highway of Life]

There is one reason in particular why always wrapping code in curly braces is a good idea: You will never accidentally add an unconditional statement that was meant to be conditional, because you need to add braces once you want to add a second statement inside the if. And as for the other part of your argument PHP has curly braces, we can't just "do away" with them, so we can as well use them consistently. Giving "{" its own line is really mostly an arbitrary choice, although I think it does improve readability, but just as well would a requirement for empty lines before and after long statement lists. I do not think it hinders readability however.

Hi Nils, have a question on this.
Example #1:

Code: Select all

if ($something) call_foo(false); 

Example #2:

Code: Select all

if ($something)
    call_foo(false); 

Example #3:

Code: Select all

if ($something)
    call_foo(false);
else
    call_bar(true); 

I could see example 3 really being an issue, and example 2 to a lesser degree. But what about example #1? For really short conditionals and code, does it really make sense to write out Example #1 as:

Code: Select all

if ($something)
{
    call_foo(false);
} 

I am a fan of using curly braces for two reasons:

1. Readability - you don’t mistake where conditional statements begin and end.
2. The Oops situation - You can't accidentally add unconditional statements that are supposed to be conditional statements.

But at the same time, if Example #1 is defined on a single line in such short statements, is it a problem to use it that way?

-------------

What is the rational for switching from lowercase identifiers to CamelCase identifiers?

[naderman]

Code: Select all

if ($x > 3 && $x < 7) echo $x; $x = substr(foo($x), 5);  

Easily happens that you end up doing something like this without the braces. The statement is always executed, even though the formatting makes it look like it will be conditional. That's part of what I meant about braces making it absolutely unambiguous.

What is the rational for switching from lowercase identifiers to CamelCase identifiers?

It has become much more common in PHP projects and it's part of the autoloading standard for PHP 5.3.

Now tabs vs. spaces. I work with a lot with both. It's true that sometimes you have to press delete/backspace a few times more (usually indentation is taken care of by an editor with tab/shift+tab or another key combo though). I have found it is much easier to put code in wikis/forum posts emails etc. when using spaces, not sure if that even counts as an argument. Your point about it being tradition in phpBB is certainly true, which given that it doesn't really make a big difference probably counts