Kevin Speaks

Drupal: I wub you, I wub you not

All of the usual critiques have some basis in fact and some basis in developer irritation. Drupal has long since reached the point where its breadth and depth commonly exceed the capability of individual minds to grasp them easily, and it is changing fast. While I could certainly spend some time griping and moaning about the many petty annoyances Drupal has caused me to date, its effectiveness and the enthusiasm of its proponents so far outweigh them that I cannot in good conscience do so.

So this is what I will gripe about instead: coding standards as a symbol of orthodoxy. If you’re interested, check out Drupal’s formal statement of coding standards. Many of these tenets are well thought out, popularly agreed upon, and many qualify as best practices. If you happen to like being chided, some bright young coders put together a module named, in an egotistical but daring move, simply “coder” — a module whose purpose is to scan your source code and tell you where you have failed to obey these standards. Despite the fact that Drupal is designed to be modular (i.e., you drop the module in and its just works), a large portion of these standards is justified as “fostering” code accessibility. Well and good, especially in consideration of my points about docblocks below.

How can these standards be put to use? Let’s consider one non-optimal standards enforcement case.

In this response to a rather inventive idea for a module…

…I see little evidence of following Drupal coding standards:

- docblocks not formatted correctly
- spacing and indentation incorrect
- typos in comments and variable names
- incorrect formatting of variable names and constants

I’m afraid this module needs much more work before it can be considered for full project status.

…we see standards compliance being used to reject an idea because of its superficial failure to meet Drupal’s coding standards. Moreover, this was an idea put forward by someone who clearly does not speak English as a first (or even, strictly speaking, as a second or third) language. Even MORE moreover, it was an idea I could *really* have used if it were implemented. (For fairness’ sake I should admit that I have no idea how meritorious the code for this module actually was; my objection here is only to the use of the coding “standards” to bounce an idea from entry.)

Acknowledgement: I believe Joachim’s response here is not snotty, as it may appear on the surface, merely frustrated. If you want a dose of snot, visit Symfony’s forums — and bring plenty of kleenex.

So, let’s assume we strictly follow (for instance) Drupal’s docblock imperative — not a bad idea, one would think. EVERYONE knows that commenting code is ALWAYS a good thing, right?


// noteresource.inc
/**
* Callback for creating note resources.
*
* @param object $data
* @return object
*/
function _noteresource_create($data) {
global $user;

...code....
}


Okay, so what useful information does this docblock convey?

1. That _noteresource_create's purpose is to (gasp) create a note resource.
2. That the parameter $data must be an object -- in other words, "this parameter *might* be anything so long as it is expressed through an object*
3. That the function returns an object -- which could, again, be anything (though we may presume it will be a noteresource-y type object)

This style of documentation, which is pervasive throughout the drupal codebase, is empty of information. We can almost always tell what the function does based on its name, so documenting the function's purpose is redundant; on the other hand, arrays and objects are so ubiquitous and so amorphous in PHP that indicating them without detailing their structure is 100%, absolutely, completely worthless. As always, the PHP recourse is to either a) dig into the code or b) call print_r an awful lot.

My other major standards gripe has to do with indenting and brackets. The Drupal standards (which I have no intention of obeying; I will use the Grammar Parser to achieve compliance when the time comes) are very specific about using 2 spaces for indents, not 4, and using hanging curly braces. This tends to result in rather unfortunate tangles of nested array definitions, difficult to read logical constructs, and (if you'll pardon me for being snooty for a moment) a very mushy aesthetic. It is important to remember that every ugly piece of code has a beautiful piece of code hidden inside it, waiting to be set free...

These two major gripes bring me right back to TimToon's very apt rant on this topic. I hear ya, man -- I hear ya.

Tags: code, coding standards, drupal