WordPress coding standards

Recently I have been working on some WordPress plugins (in fits and spurts, since I generally try to avoid PHP), in an effort to replace certain plugins that I am using on this site which work but are not ideal. In the course of doing so, I was led to investigate the WordPress coding standards, first because of concerns over what I was seeing in the WordPress codebase, but also because WordPress plugins are expected to conform to the WordPress coding standards, particularly if they are to be listed in the wordpress.org plugin directory.

The first issue is the format of the standards—ostensibly, they’re documented at the WordPress Codex, but that page incorporates by reference the PEAR coding standards (which are themselves dense) as well as a post to the wp-hackers mailing list from July 2006. It’s not clear what governs when there’s a conflict between the various incorporated documents, nor if there’s any active process to maintain the coding standards and ensure that they reflect best practices. One thing that would really help coders unfamiliar with the WordPress codebase would be a quick reference, particularly with a focus on configuring editors (at least emacs and vi) to give the desired result. I would also suggest that if it is too difficult to get an editor to produce the desired indentation and formatting automatically, that may indicate that the standard in question should be re-evaluated as to its sensibility.

Another issue is that many of the standards are presented without justification—rather than being told why you should write your code a certain way, you’re just given a list of edicts. As an example, contrast the WordPress coding standards with the Erlang coding standards. Note that the Erlang coding standards are designed to be instructive, explaining why a certain style is preferred over others. I would also point out that rather than dwelling on nit-picky formatting issues, the Erlang coding standards extensively discuss code design issues (such as function size and complexity) which are more likely to have an impact on code quality.

One of the most substantial points of contention I have with the WordPress coding standards—and one which affects code quality—is this:

If at all possible, omit curly braces.

Always using braces is considered to be a basic and straightforward code safety step which eliminates the risk of a mishap later on if a single-line conditional or loop body happens to be expanded. Even if readability is impacted by putting braces around single-line blocks (which I consider a dubious claim), what’s more important: code quality, or readability? I think code quality had ought win, particularly where there are security implications.

I also bristle at the notion of using tabs in a source file, although I suspect that’s more because I am coming to this from a Python background, where spaces are the norm. Speaking of spaces, there’s one other aspect of the WordPress coding standards that struck me as nonstandard, and that’s the convention on using spaces in statements:

Always put spaces after commas and on both sides of logical and assignment operators like “x == 23“, “foo && bar“, “array( 1, 2, 3 )“, as well as on both sides of the opening and closing parenthesis of if, elseif, foreach, for and switch blocks (e.g. foreach ( $foo as $bar ) { ...). When defining a function, do it like so: function myfunction( $param1 = 'foo', $param2 = 'bar' ) { and when calling a function, do it like so: myfunction( $param1, funcparam( $param2 ) );

I don’t object to using spaces around logical and assignment operators, but inside parenthesis? In my opinion (and in my experience, trawling through WordPress code) that causes readability to take quite a hit. However, these two issues are ‘religious issues’ among programmers, much like emacs vs. vi. Neither is likely to affect code quality or software safety; instead they’re stylistic concerns, and I know raising a fuss is unlikely to do much. When it comes to the use of braces, though, omitting braces whenever possible just strikes me as an unnecessary risk, particularly given WordPress’s track record with respect to security.