eZ Community » Forums » Discussions » The eZ Coding standards need you !
expandshrink

Thursday 26 May 2011 6:09:02 pm - 21 replies

» Read full blog post

Introduction

In our continuous effort to open eZ Publish to both our community and professional partners, we have worked on establishing coding standards that will help uniformize how our software is written and organized.

Since you, community members, are contributing more and more to eZ Publish, by means of pull requests or extensions, it only makes sense to ask for your feedback before we publish a first version of these standards.

Thursday 26 May 2011 8:46:07 pm

Hello Bertrand,

Thank for this, that's VERY useful !

I'm a bit confused about conding standard on class name. You say that class name are Upper Camel Case with a prefix "ezp". But ezp doesn't begin with a capital so it's not Upper Camel Case ? 

Also you give an exemple "FooProvider::factory()" and it's not prefixed with ezp and is Upper Camel Case. So, is prefixed class with ezp only for internal used in eZSystems ? What should we use in extension ? Is a prefix needed ?

Cheers !

Thursday 26 May 2011 9:08:26 pm

Hello,

Thank you for this big work ! What about //autogentag// in extensions ?

Friday 27 May 2011 11:53:49 am

Hello,

Thank you for this big work ! What about //autogentag// in extensions ?

It is valid for extensions built by our build server, but won't be applied to community ones, as they're not built this way. This would require a completely different project I'm afraid sad.gif Emoticon

Friday 27 May 2011 11:58:18 am

I'm a bit confused about conding standard on class name. You say that class name are Upper Camel Case with a prefix "ezp". But ezp doesn't begin with a capital so it's not Upper Camel Case ? 

Also you give an exemple "FooProvider::factory()" and it's not prefixed with ezp and is Upper Camel Case. So, is prefixed class with ezp only for internal used in eZSystems ? What should we use in extension ? Is a prefix needed ?

About Camel Case, the standard is actually LowerCamelCase due to the prefix. It isn't an easy question, actually, but I would propose the following:

  • The class name, prefix ignored, uses UpperCamelCase
  • The prefixes for ezpublish are ezp (for ezpublish) and ezx (for ez extensions)
  • Community / Market extensions must use their own prefix, either based on the extension name or the provider name

So yes, ezp / ezx are to be reserved to eZ Systems, and a prefix is required for extensions. We will update this when we start using namespaces ourselves (soon !).

I'll update the document accordingly, thanks !

Oh, and the FooProvider class is of course a mistake, it will be fixed to ezpFooProvider happy.gif Emoticon

Modified on Friday 27 May 2011 12:08:58 pm by Bertrand Dunogier

Friday 27 May 2011 1:07:21 pm

Looks good.

"Torough documentation"  should be "Thorough documentation"

No mention of line length?

Friday 27 May 2011 2:19:01 pm

Looks good.

"Torough documentation"  should be "Thorough documentation"

No mention of line length?

Thank you for highlighting my english mistakes in huge black letters, Bruce, I'll fix this soon happy.gif Emoticon

Did I really forget line length ? My god, thanks, todo list as well !

Friday 27 May 2011 2:57:08 pm

Hey Bertrand

Opps. Sorry about the big back letters - cut n paste from the google doc.  Had assumed that they would be stripped on publishing since headings are not available in the OE toolbar. What else can be pasted into these???

Are there plans to create/release a php CodeSniffer rule set based on the standard?  

Cheers
Bruce 

Bertrand B

Friday 27 May 2011 3:05:54 pm

Opps. Sorry about the big back letters - cut n paste from the google doc.  Had assumed that they would be stripped on publishing since headings are not available in the OE toolbar.

Hmmm headings ARE available in the OE toolbar, but not when replying in comments... maybe they're just removed from the UI but not from the supported XHTML? This wouldn't be surprising...

No offense taken anyway, it was kinda funny blunk.gif Emoticon

Are there plans to create/release a php CodeSniffer rule set based on the standard? 

It is part of the plan, yes !

Monday 30 May 2011 5:37:47 pm

I don`t wanna use xdebug.... I am stuck with Zend Debugger happy.gif Emoticon

So the doc should say should use a debugger.

Monday 30 May 2011 9:16:50 pm

Hi there. Really great work!. 

A question. Are there any plans to apply this standards specially those related with phpdoc things to the actual code? or at least, do you think that contributions related to this (changing doxygen to phpdoc) will be helpful or do you prefer community member take care of other things? happy.gif Emoticon

thanks!

Monday 30 May 2011 10:32:56 pm

Hi Carlos,

The current approach is to change the comments format by small steps when working on a specific file/class/method (see this commit for instance) but as always, you are free (and welcome blunk.gif Emoticon) to open some pull requests on this topic (and/or any other blunk.gif Emoticon)

Cheers

Tuesday 31 May 2011 9:57:18 am

I don`t wanna use xdebug.... I am stuck with Zend Debugger happy.gif Emoticon

So the doc should say should use a debugger.

Hehe, okay, I will make the title more generic, but Xdebug will still be recommended, as quite a lof of developers don't use a debugger at all, and we recommend Xdebug. Thanks blunk.gif Emoticon

Thursday 16 June 2011 11:55:19 am

Thank's for the standard.

I have a question about the the following convention:

>>

Files

Naming

Files MUST be named in lower-case, and MUST NOT use any separators (dashes, spaces,
underscores). PHP files MUST use the .php extension Template files MUST use the .tpl
extension.

>>

If i understood it right the following naming of a template is not allow anymore

because of "MUST NOT use any separator"

design/standard/override/templates/node/view/full/jac_folder_gallery.tpl

An other example you can see in github of our cjw_newsletter extension:

https://github.com/cjw-network/cjw_newsletter/tree/master/design/admin2/override/templates/node/view/full

or

https://github.com/cjw-network/cj.../tree/master/design/admin2/templates

I don't think that this is a good idea. We heavily use underscores in tpl files to have a better overview / structure over the templates. The templates often have the same name as the related ez content class name s where you can use "underscores". The underscore is also used by ez in some php filenames e.g.

kernel/content/function_definition.php

or in a lot of tpl files

design/standard/templates/popup_pagelayout.tpl

 

My proposal is to change the text to:

"Files

Naming

Files MUST be named in lower-case, and MUST NOT use any separators (dashes, spaces) except
underscores. PHP files MUST use the .php extension Template files MUST use the .tpl
extension."

What do you think?

Thursday 16 June 2011 2:34:06 pm

Hi Bertrand,

what is about the coding standard for ez templates?

I think this should be included in the document, too.

Monday 20 June 2011 4:29:18 pm

Hi Betrand

it seems to me that the heredoc exmple is misleading, as it WILL expand variables and such.

Wednesday 29 June 2011 3:59:45 pm

I don`t wanna use xdebug.... I am stuck with Zend Debugger happy.gif Emoticon

So the doc should say should use a debugger.

Made the paragraph more generic, thanks !

Thursday 28 July 2011 3:14:30 pm

Those coding standard are on PHP code only, we should probably add some coding standards for HTML, CSS and above all JavaScript.

Cheers

Friday 16 September 2011 4:17:58 am

The reply has been removed because of violation of forum rules.

Wednesday 05 October 2011 8:17:54 pm

Those coding standard are on PHP code only, we should probably add some coding standards for HTML, CSS and above all JavaScript.

How about standards for indenting templates?

I find it hard to do, because you may effectively have two levels of indentation, intermingled: the HTML and the template code.  Any suggestions on best practices for that?

Tuesday 25 October 2011 10:47:02 am

As there're a bunch of tools to check html/css/js, I think it's a waste of time to establish standard to write those...

expandshrink

You must be logged in to post messages in this topic!

36 542 Users on board!

Forums menu