[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
naderman
Consultant
Posts: 1727
Joined: Sun Jan 11, 2004 2:11 am
Location: Berlin, Germany
Contact:

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

Post by naderman »

That's a very good point. But since I don't think we will base phpBB purely on one single framework, but rather use parts of multiple frameworks it's not so simple. I would mostly consider Symfony 2, Zend Framework (2?) and maybe eZ Components.

All 3 have in common:
  • lowerCamelCase for methods and variables, UpperCamelCase for classes
  • Curly braces on their own line for class and function definitions
  • Curly braces are always required for control structures like if, regardsless of the amount of statements
  • Indent & format with spaces, not tabs
Differences:
  • Symfony and eZ Components require curly braces on their own line for control structures, Zend Framework has them in the same line as the statement.
  • Symfony indents with 2 spaces, Zend Framework and ezComponents indent with 4 spaces and
I have bolded what matches our current coding guidelines in git.

And a quote from Fabien Potencier: "The Zend framework uses spaces, not tabs, and the same goes for ezComponents, Drupal, PEAR, and many other PHP projects. ".

Symfony: http://trac.symfony-project.org/wiki/Ho ... gStandards
Zend Framework: http://framework.zend.com/manual/en/cod ... ndard.html
eZ Components: http://www.ezcomponents.org/contributin ... _standards

Desdenova
Registered User
Posts: 13
Joined: Wed Jul 22, 2009 6:45 pm

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

Post by Desdenova »

I have to say, I'm pretty disappointed in the team's decision to use camel_case across the board for everything.
Seeing as how the eye naturally interprets the underscore versus how it interprets changes in case, it seems to me that it may very well ruin the readability for most of the more obscure phpBB function names currently in existence.
If vague names are chosen instead of longer, more self-explanatory names, it may also make documentation a bit more of a hassle to sift through when trying to work with the codebase. That could lead to unnecessary complications and frustration for third-party developers. That in turn could lead to people that previously worked with phpBB turning away from it and going elsewhere.
Well, I'll keep it short by saying that it could lead to a lot of things happening.

In the end, I must state that I oppose this decision, and if I code anything to work with phpBB4 I don't think I'll be adhering to the camel_case clause of the coding guidelines. I prefer my code readable; I don't care about following the crowd.

User avatar
MasterZ
Registered User
Posts: 28
Joined: Sat Jan 29, 2005 8:23 pm

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

Post by MasterZ »

I know that my opinion in this matter does not count for much, but I have to say I much prefer underscore to camel case. I think CamelCase is very hard to read, especially when using multiple words and using a lot of them throughout the website.

I like how Obsidian put it in IRC
03:01 Obsidian ThisIsCamelCase. ThisIsWhatCamelCaseWillDoToYourEyes.
03:01 Obsidian This_is_not_camel_case. This_is_what_it_will_do_to_your_eyes.

User avatar
ameeck
Registered User
Posts: 86
Joined: Sun Nov 13, 2005 6:43 pm
Location: Prague, Czech Republic
Contact:

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

Post by ameeck »

MasterZ: You will hardly see a function having more than 3, max. 4 words in their title. Look at these common examples, seem difficult to read?

Code: Select all

$this->getUserEmail();

$this->fetchAll();

$auth->authenticateUser();

$user->findByUsername();

throw new BadRequestException(); 
Please think before you post.

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

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

Post by EXreaction »

Using them in function calls is not quite the same as in variables. Function calls and classes I don't mind so much.

I do not believe we require naming schemes to follow the coding guidelines for modifications anyways and I wouldn't think that we would do so for plugins in 4.x.

User avatar
ameeck
Registered User
Posts: 86
Joined: Sun Nov 13, 2005 6:43 pm
Location: Prague, Czech Republic
Contact:

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

Post by ameeck »

EXreaction wrote:Using them in function calls is not quite the same as in variables. Function calls and classes I don't mind so much.

I do not believe we require naming schemes to follow the coding guidelines for modifications anyways and I wouldn't think that we would do so for plugins in 4.x.
EXReaction: If we use some autocalling mechanism through magic methods for event or handle functions and similar things, we might have to enforce MODs to use a naming scheme. They wouldn't work otherwise
Please think before you post.

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

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

Post by EXreaction »

If it doesn't work you don't need to enforce it obviously as it'll enforce itself. ;)

ToonArmy
Registered User
Posts: 335
Joined: Fri Mar 26, 2004 7:31 pm
Location: Bristol, UK
Contact:

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

Post by ToonArmy »

EXreaction wrote:If it doesn't work you don't need to enforce it obviously as it'll enforce itself. ;)
Yes but then you don't want two different naming schemes, that's just confusing.
Chris SmithBlogXMOOhlohArea51WikiNo support via PM/IM
Image

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

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

Post by EXreaction »

In the code you guys write/accept you can require camel case if you want, but it should not be required for 3rd party plugins to be validated.

ToonArmy
Registered User
Posts: 335
Joined: Fri Mar 26, 2004 7:31 pm
Location: Bristol, UK
Contact:

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

Post by ToonArmy »

EXreaction wrote:In the code you guys write/accept you can require camel case if you want, but it should not be required for 3rd party plugins to be validated.
Okay, but that's not what's being discussed here. The MOD team can do as they wish with their policies.
Chris SmithBlogXMOOhlohArea51WikiNo support via PM/IM
Image

Post Reply