I would love to see that we make our developer’s lives easier while doing WordPress. One step to do so is to offer a clear coding styleguide and to apply it on the codebase. Because for most of the code it is not (“Legacy is so WordPress 3.0” I heard someone from the other side of the room). I put this blogpost online because I’d like to see some feedback/discussion previous to this weeks developer meeting.
From what I’ve learned over the years with coding standards, each project might have other ones. Further I learned that the PEAR and ZEND FRAMEWORK coding standards are pretty much well adopted in the PHP area. The good thing with those coding styleguides is, that they are well documented and more or less well known. And we can handle them with ease in quality control because tools exist for those out of the box. Most styles I had in PHP projects then were somehow based on the one or other one.
I know this is the WordPress project and things should be easy right upfront, so please take my question seriously and do not feel offended: Why not switch over to PEAR or ZEND FRAMEWORK styles? Or to just get more out of those? The project can benefit in many ways. The current styleguide we have is pretty much not ready and fragmented (see links below). Next to this, the (somehow) existing style is not constantly applied to the codebase so it does not make a difference if the current or a new one is applied. It should be pretty much the same amount of work.
Next to clarifying which style to apply (it might be some other/own style as well, PEAR / ZEND is only a suggestion (albeit a very preferable one)) there should be taken care for the coding style on each file then. This is some work and it should be coordinated otherwise it looks impossible to me that developers will constantly take care. I suggest to do this pre the 3.0 first beta release. So all beta-testers will see a nicely-ordered codebase there and patches can be easily applied. I can offer to create tools that can be used in support of applying standards to the code until the 3.0 feature-freeze date on February 15, 2010.
I know that those things aren’t easy to decide so I would love to see feedback here to get a first overview. If you comment on your prefered coding styleguide, please add some lines how you used it already and what your experiences are. I’ll start with my own comment. I’m aware that there are personal preferences. I know some programmers who even do not join a project if they do not accept the coding standard used therein. But I have no fear that we meet those here in the project :).
Links:
- WordPress Coding Style by Matt and Ryan (written down by Mark Jaquith) (Originally)
- WordPress Coding Standards (the Codex Page)
- PEAR Coding Standards (External Project)
- ZEND Coding Standards (External Project)
Follow Up: Coding Standards Summary of the last Week (28 Jan 2010; by hakre)
hakre on wordpress 
IMHO the current somehow describben wordpress coding style looks ugly especially because of the spaces inside the function brackets. I think it’s hard to read. In general I can adopt to any style from what I know by doing work in other projects. Next to this there is a general personal preference of the ZEND or PEAR guidlines because they are well documented and easy to use. I experiences that those make it easy to work together developer-wise as I did in some projects.
For line-endings I prefer UNIX and I would love to see those ?> removed from files where they are not needed (but not the configuration file).
I dislike PEAR formatting and completely loathe ZEND formatting. If documentation is an issue, we should fix that! And I’m okay with removing the ending
?>from PHP files. I’ve started doing that myself as standard practice.Because I don’t like them. 😉
Thanks for joining by Matt, but to what are you referring? The spaces in the functions? Or a certain coding standard? Or coding standards in general? Or was the the file-endings (?>) ?
From spending 5 seconds looking at both the PEAR and ZEND coding standards I can safely say that I disagree with both of them on fundamental levels.
I also disagree strongly with the removal of
?>file endings from files which are not user-editable.As for line-termination we work with the svn native eol-style for all files except those which are expected to be edited by the end user which have windows line ending.
Overall, we need a simple set of coding standards which make the code easier to read and maintain and are themselves easy to read – they should be as short as possible!
Do not forget they are a guide and a standard to aspire to – it is much more important that the code /works/ than it is written against a particular style guide.
Thanks for the comments westi, I really appreciate them.
Regarding PEAR and ZEND it was a suggestion (a personal one) and as far as I can see it’s not that widely accepted by current core devs (which is actually not a surprise to me). I suggested that because it might help to find more developers. For any larger project with multiple coders I think it becomes more and more important to have a style everybody is applying to. If this isn’t the case in this project, it would be good to know (and show) upfront. The codex page is signalling something else IMHO. It might be an option to have no/any style in favor of a certain one. Why not? Why to reduce the case to a specific option instead of multiple? But that is maybe not that what you’re talking about. Just free-thinking.
Regarding the line endings I was not aware of the SVN property set. Just reviewed that and I’m personally okay with it, that makes sense and solves the issues I had as well.
I prefer the format we currently have and also am against removing ?> from non-user editable files. Without it, there’s no easy way to tell if the file is fully uploaded or not.
Don’t fix what (in my opinion) isn’t broken. 🙂
/* is this the end of the file -> */ ?>some html cutted away by the faulty FTP upload
<?php
/* enourmous important PHP code left following: */
an argument I hardly can follow, but I know it's said here and there.
So what's broken here and what to be fixed should be the question. Having whitespaces in files at their end where they do not belong to are a bummer, right? But do we have those in the codebase? Or isn’t that not right and whitespace on the end are OK for PHP 4.3 and above?
Hi,
I just had a quick glance at the PEAR and ZEND styles and while they seem to have standards for as it seems everything, they are also inconsistent, e.g. with curly braces, which after function bar() are in the next line, but after if (…) are not.
I’m totally in favor of the Standards suggested in the Codex/Mailing list. I had never dealt with Coding Standards before starting WP Plugin Development and I came to the conclusion that it makes programming a lot easier.
I especially like the usage of spaces/blanks in the WP Standards (on both if/foreach/… and on function(), and function calls), as it makes spotting the term/variable I want to work on much easier. And I’m also loving the “something” == $foo checks in conditions.
Linebreaks are ok with the SVN command, ?> should be included at the end of the file.
And stick to the mentioned WP Coding Standards, but apply them to all code.
Best wishes,
Tobias
If you favor spaces next to the inside part of function definition braces, how to call an empty function? you do it this way?
<?php template_tag(); ?>or do you put two spaces inside the empty call as well like this: ?
<?php template_tag( ); ?>No, that would be empty braces ().
One thing I wish we would change is the requirement of curly braces around control blocks. It is very annoying to be debugging code and have to constantly add braces around a control block anywhere I want to get output for testing.
On a lesser degree, I would like to see all curly braces move to new lines so the block stands out even more:
if(true == $foo)
{
do_something();
}
else
{
do_something_else();
}
@prettyboymp I agree with you except that I prefer to place the opening curly on the same line as the condition like this:
if (true == $foo) {
do_something();
}
else {
do_something_else();
}
I spend way too much time adding curly braces and removing unnecessary php delimiters.
Also, I don’t get the “use tabs instead of spaces” because spaces are more consistent between editors.
I’m fine with the Zend standards, but they’re pretty far removed from the current code base. Can you imagine having to change from underscores/lowercase to camelCase?
Anyway, I like the existing standards (in the codex and in the wp-hackers message linked above) with some small points of contention including:
1) I don’t like leaving off curly braces from single line if/elseif/else blocks. While using them all the time will increase the character count in our files, it make sure things are always clear (I know, indentation can still make things fairly clear, but braces are better in my opinion) and it helps to avoid needless errors that arise when additional lines of code are added to the block (as well as keeping the conditional lines from showing as “changed” in the repository in these cases).
2) I do like to leave off the closing PHP tag at the end of files. I’ve found (in my experience) that it causes more problems than it fixes. I see a lot more issues with an extra whitespace sneaking in after the ?> than partially uploaded files (which do happen, but most people don’t look for the ?>…they just re-upload everything).
3) I prefer to use curly braces around variables parsed in strings. It’s completely optional in most cases, but sometimes doing a search/replace (such as replacing $var with $myArr[‘var’]) will run into issues if the variable is interpolated somewhere.
Having said that, none of these are major, and I think enforcing what we already have (and maybe clearing up and expanding the documentation) will do us more good than adopting new standards.
As I have mentioned in the ticket at http://core.trac.wordpress.org/ticket/11971#comment:1, there are two particular inconsistencies in core. The first is
__('Blah');versus__( 'Blah' );. The former outnumbers the latter 3:1 in core, but the latter is technically correct. I actually like no spaces as an exception for __() and _e(), as it looks clean and is easy to read. We really just ought to pick one and do a massive replace effort in one changeset.The second would be whether a space should be before !, as in
if ( !empty( $blah ) ). The standards don’t specify, and we go back and forth in patches and commits.I add to the list the usage of whitespace in docblock comments as well as it would be usefull to provide rules/suggestions how to format docblock comments as well (e.g. how to signal optional parameters).
I don’t like the PEAR standards at all but I do like Zend’s. In fact, I already use most of Zend’s. I despise the pass-by-reference guideline when it comes to passing arguments to class methods, and I don’t support the closing ?> as it opens up too much risk, if the coding standards were adopted by plugin devs, for whitespace errors that are hard to track down.
Pingback: Coding Standards Summary of the last Week « hakre on wordpress
Another one for the list: Whitespaces in the brackets on class instantiation with the new operator.
Pingback: Docblock comments and more in code guidelines / standards « hakre on wordpress
Pingback: Prevent Code Injection in PHP include files « hakre on wordpress
Pingback: PHP Code Sniffer, Eclipse and Wordpress « hakre on wordpress
Pingback: WordPress Outage Feedback | hakre on wordpress