Webel UML for PHP: necessary departures from Drupal coding and documentation standards: special OO bridge method naming conventions; and UML-friendly 'I' prefix Interface names

HOT TIP: this content is flagged as highly recommended !
Keywords

The OOE = Object Oriented Examples = One Of Each and Flag Plus tutorial modules attempt wherever possible to comply with the Drupal7 coding standards and Drupal7 object-oriented coding standards as well as the Drupal7 API documentation and comment standards. Indeed if you look at the Coder issue queue you will see that it is unlikely that anybody else in the history of Drupal has spent as much time putting their contributed module code through the Drupal Coding Standards and Coder PHP Code Sniffer wringers and reporting coding standards issues and Coder issues on Drupal.org as Webel has.

However, in order to support the Webel recipe for UML-friendlier PHP, and in order to support reverse engineering with PEAR:PHP_UML, and in order to support convenient modelling in a UML tool like MagicDraw UML, it is essential that certain departures are systematically adopted.

The current Drupal Coding Standards - including the current attempts at OO standards - are clearly not developed with graphical UML support in mind, and if you want to work with graphical UML for PHP using the advanced Webel recipe demonstrated on this site then you MUST ignore some of the Drupal Coding standards and instead adopt the very systematic Webel recommendations listed throughout this site, and developed especially for use with PEAR:PHP_UML (in combination with advanced UML tools like MagicDraw UML).
"Yes, I am telling you in no uncertain terms that I know heaps more about object-oriented programming - not to mention graphical software engineering with Unified Modeling Language (UML) and Design Patterns - than basically the entire Drupal7/8 core development team and you should listen to me, not them, in the matter of UML-friendlier object-oriented PHP coding practice."

Dr Darren Kelly, The Drupal Heretic, Webel IT Australia.

When using the Webel UML recipe for PHP please ignore all of the following Coder review warnings in classes and interfaces in the fully OO layer.

In spite of the Java-like Drupal OO coding standard recommendation that:

'Methods and class properties should use lowerCamel naming'

As of 2015-04-20, if you use $camelCase for the matching parameters of those private variables in setters you get (because the current Coder sniffer rules are just following the completely inconsistent Drupal Coding Standards):

ERROR | Variable "flagBanner" is camel caps format. do not use mixed case (camelCase), use lower case and _

No no, on the Drupal Island, after at least a couple of years discussion, and a huge waste of my time, it still has to look like this:

class StupidDrupalConvention {

 private $camelCase;

 public function setCamelCase(type $lower_case) {
  $this->camelCase = $lower_case;
 }

}

jr-banghead.gif

Have the Drupal8 Gods seriously been putting their code through Coder like this just to prevent copious Coder error reports ? Do the members of the Drupal Coding Standards team actually think that looks OK for OOP ?

It's one of the stupidest things I have ever seen in over 3 decades spent working with computer languages, programming, and software engineering. For OOP, that coding standard is complete garbage, belongs in the rubbish bin, and only proves once again that at least some people involved with Drupal's painfully slow move to OOP are utterly clueless, or have never seen any decent Java code in their entire life. They have been told very clearly how embarrassingly stupid it looks but are choosing not to listen to people who clearly know a lot more about OO, even when Drupal8 is about to come out and now (2015-04-20) is the time to fix this, before it becomes yet another piece of Drupal Religion Dogma on the Drupal Island.

And speaking of religion, I will be damned if I am going to do something so utterly horrible in my contributed module code in OOE = Object Oriented Examples = One Of Each or Flag Plus, let alone let it be seen in my elegant graphical UML models. Yuck !

In interfaces:
WARNING | Interface names should always have the suffix "Interface".

Complete and utter bollocks; Ignore it. See also:

- Please get rid of the verbose Drupal "Interface" suffix naming convention !

- In the UML-friendly Webel PHP Interface names are always prefixed with capital 'I' thus ICamelCase ! This has many advantages for graphical UML modelling and IDE based prompting (and saves typing) This is knowingly NOT the Drupal coding standard ! (And if you follow this policy note link, please notice how much more compact the diagrams are without painfully adding 'Interface' everywhere, because when you have graphical UML support an Interface has a special symbol anyway).

If you wish to use no prefix or suffix at all (i.e. trust PHP and your IDE to know that an interface is an interface), and perhaps use say the Impl suffix convention for default implementation classes, please feel free to do it, but you will find there are lots of advantages when using your IDE and UML tool if you use a 'I' prefix for interfaces.

In parameters type hints for things like a $node that are only known to be a stdClass, simply use stdClass (as long as you are using at least PHP5.3) as the type hint and ignore this warning, which I consider a Coder bug:
ERROR | Expected "object" but found "stdClass" for parameter type.
Unfortunately PEAR:PHP_UML can't yet mind read, so unless you want your UML models to know nothing about the parameters of hook operations please ignore this, and do please include the @param and @return info:
WARNING | Hook implementations should not duplicate @param documentation

Of course, under normal circumstances this won't occur anyway, because you can't reverse engineer .module and "Flatland" .inc include files with function hooks anyway unless you use this: DIRTY TRICK for reverse-engineering "flat" Drupal7-style .module and .inc PHP files into methods of Webel-style wrapper @Components.

Special case when using a special bridge Class to delegate between Drupal7 hook and handler functions and full OOP

Finally, when working with the OOE = Object Oriented Examples = One Of Each tutorial module and OO bridge for Drupal7, there is a special case explained at: Webel/OOE: delegate methods (such as hook and handler implementations) of an OOE bridge Class SHOULD use lower_case_underscore_separated() [not camelCase()]. All other Classes and Interfaces should use camelCase() for operations/methods (as per Drupal8).. Please in that case ignore this Coder report:
ERROR | 'Methods and class properties should use lowerCamel naming'

Basically, in the Webel recipe, an OOE bridge Class should always use a signature for special delegate methods of hooks and handlers that also look like the .module hooks and handlers that delegate to them (but without the module_ prefix), so that you know they are indeed delegate methods for the hooks and handlers. Simple, consistent, and sensible.

See also the very extensive issue tracking under the Coder module review page !

Visit also