[module] Coder

Compatibility:

0
Project page quote (external)
Project page quoted on: 
2014-02-20

The Coder project includes two developer modules that assist with code review (Coder Review ..) and code manipulation (Coder Upgrade ...).

Coder Review

This module utilizes rules (mostly regular expressions) to review source code files for code that 1) needs to change due to Drupal API changes and 2) does not satisfy Drupal coding standards.

Required by modules [Drupal7[

Also from Code Sniffer:

Coder Sniffer is a part of coder (7.x-2.x branch) and a tool to help write code for Drupal or its modules.
The project provides a coding standard for PEAR's PHP_CodeSniffer based on the Drupal Coding Standard.

Why?

This sniffer has been created because of the need to run coding standards check without requiring a full drupal installation. This is great for checking code validation on a standalone server without a drupal site, checking a single file from a code editor (Eclipse, Textmate, etc.), setting up pre-commit hooks on all files being committed.


Dr Darren's summary

Coder is useful for checking for missing API docs and API doc formatting, but is still mostly more trouble than it's worth (because of the current rules) for enforcing the current Drupal coding, commenting, and documentation standards that I'm not a great fan of anyway. See below for why.

2015-04-05 I acknowledge that the Coder maintainers have made a sincere effort to consider my many suggestions and to address them as much as Coder as a "lint" can; I have made unfortunately much less progress with the actual Drupal Coding Standards and Drupal Documentation Standards effort, especially regarding OO coding standards.

Applying Coder to a large object-oriented Drupal module with typical agile documentation and inline comments is currently about as much fun as pulling your own wisdom teeth with a pair of pliers and no mirror

Phew, just as well it told me about .. all of that really dangerous trailing whitespace my IDE introduced that PHP does not care about, and those poisonous missing full-stops on very brief inline comments (which I insidiously placed right after the code they remark on), not to mention the sorely missed documentation on those really confusing nasty getters and setters:

  /**
   * Gets the thing.
   *
   * And just as well I had to add the missing documentation 
   * because you would never have guessed that from the
   * getter's method  name or the return type.
   *
   * @return IThing
   *    The thing.
   */
  public function getThing() {
    return $this->thing;
  }
 
  // Make sure no nasty whitespace here might hurt somebody.
 
  /**
   * Sets the thing.
   *
   * And just as well Coder told me to document the  
   * parameter with exactly the same name as the
   * class variable I am setting, solving that mystery.
   *
   * @param IThing $thing
   *   A thing. Now you know.
   *
   * @return IParent
   *   This. With a full stop.
   */
  public function setThing($thing) {
    // Perform checks: note capital P and this full stop.
    //if (empty($thing)) {
    // NO a naughty inline comment above before some incomplete code !
 
    $this->thing = $thing; // NO it's an inline comment after the code !
 
    //TODO oops, forgot that important space after the //
 
    //bugger: double naughty, no space and not a Capital Bugger !
 
    dpm($this->thing);
    // DEBUG
    // OUCH, no full stop or exclamation mark, it must be DEBUG! or DEBUG.
    }

Phew, just as well I documented those getters and setters, otherwise I would have no idea what they are doing ! So glad I spent my time on it, all is shiny and well. (And it even caught the full stops missing on my one word comments, the really really important stuff that matters before I die.) Wow, that's value adding !

God Bless Drupal Coding Standards. I am just in love with them, it's 'true', I mean 'TRUE', because the the official PHP manual says:

'To specify a boolean literal, use the keywords TRUE or FALSE. Both are case-insensitive.'

So obviously Drupal has to make you USE THE CAPS KEY so that:

$switch = TRUE;

is clearly much better than:

$switch = true;

I mean honestly I really have trouble reading these;

public function method( $optional = null ) {
}
 
$off = false;

Wow, 5 UNPAID days later (including my weekend nights) and my code and documentation now do .. basically exactly the same thing as before.

As you can see from my many issue reports below, and while I understand the need for some kind of coding conventions, so far I find Coder (because of the currently adopted rules) rather annoying to use, at least for my OO coding practices and my coding habits. (It does a good job of parsing and reporting on those rules, but as long as I don't like those rules much I won't give Coder 5 stars.) I acknowledge that it is very difficult to develop a tool like Coder, and it is also very difficult to make everybody happy, and I am grateful to the Coder developers for their efforts to date. But basically, as it currently stands, it (together with the Drupal documentation and coding standards) are IMHO way too "bossy", and not well suited to a fully object-oriented project like OOE = Object Oriented Examples = One Of Each.

I am never going to be able to pass all of those tests, despite my very best efforts.

Concerns, issues, warnings, gotchas
OO: Coder complains about camel caps (camelCase) argument to setter method in Class

PHP_CodeSniffer-1.5.3
Project coder (7.x-2.2) (installed using drush pm-download coder --destination=$HOME/.drush)

I have marked this as major, because from the perspective of an object-oriented developer this is making it extremely hard to use Coder to screen fully object-oriented modules, it is causing most Classes with getters/setters to fail the Coder tests.

Typically - and in full compliance with the Drupal object-oriented naming conventions - class variables are lower $camelCase, and may offer a Java-style getter/setter pair, with the setter like public function setCamelCase($camelCase).

Coder is complaining incorrectly about OO-style setters like this:

class DefaultMenuItem extends DefaultModuleHelper implements IMenuItem {
 
  private $accessArguments;
 
  public function setAccessArguments(array $accessArguments) {
..
  }
 
 protected $pageArguments;;
 
 public function setPageArguments(array $pageArguments) {
..
 }
}

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

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

It is perfectly valid, consistent, and desirable for the argument/parameter to be like $accessArguments or $pageArguments.

(The above examples are taken from my educational OOE = Object-Oriented Examples tutorial module, which demonstrates an object-oriented bridge to Drupal7, available via the sandbox: https://www.drupal.org/sandbox/webel/2120905).

affects version: 
Project coder 7.x-2.2
Inline comments before code (as opposed to text) should not enforce: Inline comments must start with a capital letter

This spawned from Check for proper inline comment formatting.

I disagree with this enforcement when inline comments are used to comment out code:

ERROR | Inline comments must start with a capital letter

Inline comments are often used to comment out code that one is working on, or to record a few lines of code that did not work or had problems or such. They may also be used to comment out code that is not complete, such as an optional else statement, or something that is still "todo". There are numerous other cases. In such cases, the capital letter rule is not applicable, the commented out code may use a keyword that is never capital.

Even the following triggers the above ERROR message.

// else {
// ..
// }

Please relax this rule, it is clearly too strict and in my opinion unnecessary.

For what it's worth, I don't even think it is required when commenting out text remarks, but my issue report here concerns inline comments on code and code keywords, which I hope you can isolate if you still insist on keeping the capital rule for inline comments on actual text.

affects version: 
Project coder 7.x-2.2
Please permit long URL text in inline comments

Spawned from False positive on commented URLs (which as far as I can tell only applies to comment docblocks).

It is often extremely useful to record URLs of relevant software engineering tips alongside code using inline comments //

Sometime these URLs are longer than 80 chars, and trigger this:

WARNING | Line exceeds 80 characters; contains 87 characters

Example: the following URL (about type casting in PHP) is longer than 80 chars and triggers the above.

My Coder review output on this educational tutorial module is currently fairly littered with the above WARNING, because I make frequent use in the code of such reference links, and they turn out to often be longer than 80 chars. I do not want to have to remove this useful and in some cases crucial information just to pass the Coder tests.

Please relax the rule to identify URLs via the http:// and https:// prefixes and permit URLs longer than 80 chars.

Such reference URLs do not always belong in a @link @endlink or a @see, they belong correctly in the code (usually under relevant code) not in doc blocks.

affects version: 
Project coder 7.x-2.2
Inline comments before code (as opposed to text) should not enforce: 'ERROR | No space before comment text; expected "//'

In the case where inline comments are used to comment out code, I do not agree with this rule:

ERROR | No space before comment text; expected "//

One reason I don't agree with it is that if I use a modern IDE like NetBeans or Eclipse to comment out code (the inline "comment out" function) it fails the above test.

Example: imagine this is some code I am working on:

  $a = $b + 1;
  //$a = $b + 2;

The 2nd line triggers the above ERROR.

There is another slight problem if one does have it formatted to meet the current Coder rule, with a space. Let's say I had it so it passes the test.

  $a = $b + 1;
  // $a = $b + 2;

Now if I say delete the 1st line and uncomment the 2nd line there is a space before the 2nd ' $a'. One has to remember to remove that space, otherwise Coder complains about the alignment. Again, if one uses say NetBeans uncomment, it does not remove that space.

Perhaps relatively trivial, but nevertheless I think this should be relaxed.

Basically, as far as inline comments are concerned, I am finding Coder far too "bossy". In general, feel that inline comments are a space/zone where developers should be free to use their own habits and practices.

affects version: 
Project coder 7.x-2.2
Please relax rule for inline Comments: 'Comments may not appear after statements'

I feel really strongly about this one. Coder currently triggers on code like this:

$a = $b + 1; // My brief comment well placed

Coder reports:

ERROR | Comments may not appear after statements.

I really find this too "bossy" of Coder (and/or Drupal coding standards) and unnecessary. As long as an inline comment is not too long (does not cause the line to be longer than 80 characters) I can see no good reason for preventing such comments.

One very good reason for permitting such comments is that one can use "tokens" or keywords like TODO, TEST, CHECK etc. after a comment on the same line and filter on it easily (with say the IDEs search functionality) to find all lines in a project "tagged" by a given token/keyword.

$pi = 4.14159; // CHECK! 

This is much harder if inline comments must come after the code.

Please relax this rule.


https://www.drupal.org/node/2304897#comment-8977983

Another situation where inline comments after statements are very useful is when there is a list of parameters like this:

public function __construct(array &$form, $title, $description = NULL) {
    parent::__construct(
        NULL, // TODO type?
        NULL // DO NOT pass $description here, display via description item.
    );

Coder wants it at least like this:

public function __construct(array &$form, $title, $description = NULL) {
    parent::__construct(
        NULL, 
        // TODO type?
        NULL 
        // DO NOT pass $description here, display via description item.
    );

But to make it clear whether the comment applies to the line above or before one has to do this (leave a line)

public function __construct(array &$form, $title, $description = NULL) {
    parent::__construct(
        NULL, 
        // TODO type?
.. leave line here ..
        NULL 
        // DO NOT pass $description here, display via description item.
    );

The 1st case, with inline comments after the parameters, is much clearer and easier.
Also, one can filter in and IDE on the '// TODO' to find and see the relevant line.
If the comment is below or above the line it refers to the search result is not clear,
one has to go to the comment line in the file then read the line above or below.

affects version: 
Project coder 7.x-2.2
Please relax requirement for @file when using OO Class or Interface per file: 'ERROR | Missing file doc comment'

The following is relatively trivial, but worth remarking on.

The current Drupal API documentation standard for @file states:

@file: Documenting files

The @file tag is placed in a docblock to indicate it is documentation for the file as a whole.

If @file is missing Coder reports:

'ERROR | Missing file doc comment'

I appreciate the sense in "the file as a whole" for procedural files with possibly many functions.

But when one is using strictly OO development with strictly one Class or Interface per file, the above "the file as a whole" is not very useful if one is documenting the Class or Interface in the docblock header of the class anyway. Repeating the 1st line of Class header in the @file section breaks the Don't Repeat Yourself (DRY) principle and leads to maintenance problems (if the purpose or statement of purpose of a class changes it has to be changed in 2 spots). I find myself simply putting 'class XYZ' in the @file block thus:

/**
 * @file
 * class BlockVisibilityKind
 */
 
namespace Drupal\ooe\Block;
 
/**
 * Encapsulates the possible visibility status options 
 * of blocks as referenced in hook_block_info().
 * 
 * UML: 
 * @link http://drupal7demo.webel.com.au/node/1151 BlockVisibilityKind @endlink
 * 
 * @author darrenkelly
 */
class BlockVisibilityKind {
 
  /**
  * 'Show on all pages except listed pages. 
  * 'pages' lists the paths where the block should not be shown.''
  */
  const NOTLISTED = BLOCK_VISIBILITY_NOTLISTED;
 
  /**
  * 'Show only on listed pages. 
   * 'pages' lists the paths where the block should be shown.'
  */
  const LISTED = BLOCK_VISIBILITY_LISTED;
 
  /**
   * 'Use custom PHP code to determine visibility. 
   * 'pages' gives the PHP code to use. '
   */
  const PHP = BLOCK_VISIBILITY_PHP;
}

When the API docs are generated I find this acceptable (it merely states that the file contains the named class, and the description of the class appears on the generated API page anyway).

Please relax the rule so that one does not need to have a redundant @file docblock if it is clear that the file is dedicated to a single Class or Interface.


https://www.drupal.org/node/2304909#comment-8982307

Closely related. The Druoal coding standard currently says:

Drupal sample for files containing one class/interface:

/**
 * @file
 * Contains \Fully\Qualified\Namespace\And\NameOfTheClass.
 */

I don't find this adds any value, it is redundant, it is fragile against change, and it just makes for more work.

Firstly, the word 'Contains' does nothing, files do contain things, yes.

Putting the Namespace in there is fragile against change. Even IDEs like NetBeans and Eclipse with powerful refactoring don't catch it if the packaging is changed.

It also does not add anything of value to the generated docs, the API module extracts nicely the correct namespace already.

Putting it a 2nd time in text does not add any value, all it does is add another error-prone text based liability.

I would get rid of the entire @file requirement in the case where a file has one class or interface (but keep the requirement that the class or interface have a docblock header).

For now, all I am using is this (enough to keep Coder quiet without having to introduce fragile, inconvenient and redundant content):

/** 
 * @file
 * NameOfClassOrInterface
 */
affects version: 
Coder 7.x-2.2
Please remove this requirement: 'WARNING | Interface names should always have the suffix "Interface"'

Firstly, since I am making so many issue reports under Coder today, a preface to the developers. I appreciate the need for coding standards (as long as they are not imposed too brutally). I am grateful for your efforts in developing Coder. I appreciate that the Coder developers are not necessarily responsible for the actual Drupal coding and documentation standards (that the tool is attempting to report on). I also appreciate that it is very difficult to make everybody happy when it comes to coding standards

I can't even begin to describe how much I want this rule to go:

WARNING | Interface names should always have the suffix "Interface"'

I repeat below my remarks made yesterday under the Object-oriented code standards guide.


As an advocate for object-oriented programming with graphical Unified Modeling Language (UML) support I am very strongly opposed to this current recommendation/convention from https://www.drupal.org/node/608152#naming, and I hope it will be relaxed:

7. Interfaces should always have the suffix "Interface".

It has likely been conceived by people who are not frequent graphical UML users, and are perhaps even relatively new to object-orientation; certainly I can see no good reason for it. In modern IDEs like NetBeans or Eclipse, and when using graphical UML tool support, it is perfectly clear already whether something is an interface or not, it is indicated by icons and symbols in the tools, and in PHP code alone by the identifier 'interface'; one does not need to also spell it out painfully verbosely with the word "Interface" in the element name, least of all as a suffix.

Like many other experienced object-oriented developers (and coming from a Java and C++ background), I use instead (depending on the project) interfaces prefixed with a capital 'I' followed by a CamelCase name like ICamelCase. This has many advantages:

- It saves a massive amount of typing !

- The 'I' acts like the Interface icon in UML and makes for much easier and more compact diagramming, which I invite you to inspect here http://drupal7demo.webel.com.au/module/ooe/uml (which also shows a gallery of UML diagrams for an educational "object-oriented bridge" module for Drupal7).

- It makes it much easier to prompt for Interface elements in IDEs and UML tools like MagicDraw UML by just prompting on the 'I'. (I have indeed tried this with the verbose DrupalInterface naming style, and believe me it is much harder, truly tedious. How on earth is one supposed to prompt on a suffix anyway ?)

I hope the "Interface" suffix convention is removed or officially relaxed as soon as possible, before it is embedded in Coder and becomes a de facto convention.

Certainly, I hope that no object-oriented contributed module projects (like my educational OOE = Object Oriented Examples = One Of Each tutorial module), are prevented from moving from the sandbox (as I am hoping to do with this https://www.drupal.org/sandbox/webel/2120905) to the accepted Drupal projects space just because they do not adopt the "Interface" convention. I certainly will never use that recommended "Interface" suffix convention, it is simply too inconvenient, too clumsy (for UML), too much work, and completely unnecessary.

Basically, I will fight "tooth-and-nail" to get rid of this currently recommended DrupalInterface suffix convention !

affects version: 
Coder 7.x-2.2
This requirement is at odds with OO encapsulation: WARNING | Only string literals should be passed to t() where possible

I appreciate this one is only a warning, and that there may be security reasons for insisting on the rule

This rule is at odds with object-oriented encapsulation:

WARNING | Only string literals should be passed to t() where possible

Example: in my educational OOE = Object Oriented Examples tutorial module (sandbox https://drupal.org/sandbox/webel/2120905) I have an interface IBlock and a class DefaultBlock that encapsulates a Drupal block. It has a private variable for the block $info, and this is used (with a lot of other stuff) to help build a Drupal block array that is then passes off to Drupal core:

class DefaultBlock implements IBlock {
 
  /**
   * From hook_block_info(): 
   * 'The human-readable administrative name of the block.'
   * 
   * 'This is used to identify the block on administration screens, 
   * and is not displayed to non-administrative users.'
   * 
   * @var string
   */
  private $info;
 
  public function __construct($delta, $info) {
..
    $this->info = $info;
  }
 
  /**
   * Builds and returns a Drupal array compatible with hook_block_info().
   * 
   * @return array 
   *   A Drupal array compatible with hook_block_info().
   */
  public function get() {
    $out = array();
 
    $out['delta'] = $this->delta;
 
    $out['info'] = t($this->info);
    // Coder: WARNING | Only string literals should be passed to t() ..
 
    if (!empty($this->cache)) {
      $out['cache'] = $this->cache;
    }
    if (!empty($this->properties)) {
      $out['properties'] = $this->properties;
    }
    if (!empty($this->weight)) {
      $out['weight'] = $this->weight;
    }
    if (!empty($this->status)) {
      $out['status'] = $this->status;
    }
    if (!empty($this->region)) {
      $out['region'] = $this->region->getName();
    }
    if (!empty($this->visibility)) {
      $out['visibility'] = $this->visibility;
    }
 
    $pages = $this->getPages();
 
    if (!empty($pages)) {
      $out['pages'] = $pages;
    }
    return $out;
  }

Coder triggers on this line:

    $out['info'] = t($this->info);

Use of string literals is in such cases at odds with object-oriented encapsulation.

That said, I don't currently have any ideas how best to handle the above safely.


A Drupal.org contributor wrote:

This is because http://localize.drupal.org, as the tools used for translation need that the string is inside the function to parse it. If a string is a constant or a variable, it will be translated only if the same string is present anywhere on drupal.

affects version: 
Coder 7.x-2.2
Coder complains incorrectly about string concatenation

From this class DefaultModuleHelper. Coder complains about this:

  protected function setFactory(IFactory $factory) {
    if (empty($factory)) {
      throw new \Exception('IFactory $factory must not be empty !');
    }
    if ($factory->getModuleName() != $this->getModule()) {
      throw new Exception(
      'The module machine name(' . $factory->getModuleName() .
      ') of the provided factory does match' .
      'The module machine name(' . $this->getModule() . ') of this !'
          );
    }
    $this->factory = $factory;
    return $this;
  }

Coder report:

ERROR   | String concat is not required here; use a single string
     |         | instead

I also tried this, it still complains:

    $error = 'The module machine name(' . $factory->getModuleName() .
      ') of the provided factory does match' .
      'The module machine name(' . $this->getModule() . ') of this !';
      throw new Exception($error);

I can't see anything wrong with either of these forms, they are perfectly acceptable PHP concatenations, I consider it a bug.

affects version: 
Coder 7.x-2.2
Commented out code blocks using inline comments give multiple indentation errors

Example: here I was playing with an alternative constructor and have commented it out for now, in NetBeans IDE, using its "comment out" function:

  //  public function __construct(array $items, $title = null) {
  //    if (!is_array($items)) {
  //      throw new \Exception('$items must by an array !');
  //     }
  //    $this->items = $items;
  //
  //    if (!empty($title) && !is_string($title)) {
  //      throw new \Exception('$title must a string (or null) !');
  //    }
  //    if (!empty($title)) {
  //      $this->title = $title;
  //    }
  //  }

Coder spits the dummy multiple times.

 
  54 | ERROR   | Inline comments must start with a capital letter
  55 | ERROR   | Comment indentation error, expected only 2 spaces
  56 | ERROR   | Comment indentation error, expected only 4 spaces
  61 | ERROR   | Comment indentation error, expected only 4 spaces
  64 | ERROR   | Comment indentation error, expected only 4 spaces

The problem with inline comments and capitals with code is already reported, I am concerned here about the indentation errors.

Commenting out code with inline comments // is a very common practice. Developers shouldn't have to waste time indenting such code pathologically.

Please relent concerning this and all other issues regarding inline comments and code. Developers do, should be allowed to, and will continue to use inline comments to comment out code, and across the board, the current rules are causing trouble. It's wasting your (the maintainer's) time, and mine.

Now just imagine how relaxed we will all be if you relax these rules. Feel the fresh air ..

Feedback only: NetBeans introduces whitespace (have to remove "by hand")

Feedback only, no action required, please close on reading.

The Drupal coding standard regarding whitespace requires:

Lines should have no trailing whitespace at the end.

Even if one has NetBeans IDE configured to use these excellent tips on NetBeans formatting settings for Drupal - which go a long way to help one meet the Coder rules - NetBeans often introduces whitespace automatically, which trips up Coder. It can be a real time waster and annoyance.

It happens for example when one hits ENTER/RETURN at the end of a line of code like this:

  $a = $b + 1;
 
  // NetBeans will put in 2 whitespaces above, they have to be removed by hand
affects version: 
Coder 7.x-2.2
Permit punctuation (like quotation mark) at start for function comment

This is trivial (low priority and a workaround exists), but worth reporting.

The following function comment is quoted from the online Drupal docs, and this is made clear by 'Quotes':

  /**
   * 'The type of list to return (e.g. "ul", "ol")'.
   * 
   * @return string
   *   'The type of list to return (e.g. "ul", "ol").'
   */
  public function getType() {
    return $this->type;
  }

Coder reports:
ERROR   | Function comment short description must start with a capital letter

Of course it's easily solved with something like:

  /**
   * Gets the 'type of list to return (e.g. "ul", "ol")'.
   * 
   * @return string
   *   'The type of list to return (e.g. "ul", "ol").'
   */
  public function getType() {
    return $this->type;
  }

But I can see no good reason why some punctuation should not be allowed in the rule.

affects version: 
Coder 7.x-2.2
Inline comments: not all cases should require a full stop, exclamation mark, or question

Calling it a bug's a bit harsh, but this really only applies if one is commenting out sentences:

ERROR: Inline comments must end in full-stops, exclamation marks, or question marks.

It could at least be relaxed from ERROR to a WARNING, calling the following errors is just plain silly.

Why is this an ERROR ?

dpm($var);
// DEBUG

Or this:

// TODO

Or this:

// CHECK

Why should I have to spend my time editing the above so that it reads like this ?

// TODO.

What is the compelling "value add" there ? I can't see one. I find it just plain annoying.

The rule should only apply to full text sentences, if at all.

affects version: 
Coder 7.x-2.2
OO: Documentation standards "overkill" (not agile enough) for getters and setters

I am currently working through application of Coder to a substantial fully object-oriented tutorial module (including graphical UML diagrams) for Drupal7, in preparation for moving from the sandbox: https://www.drupal.org/sandbox/webel/2120905.

It is taking me many days, the better part of a week, and in general, I can so far see little benefit (the "value add" is not convincing or compelling), although it has helped catch some minor problems. I honestly almost resent it, is has become a very expensive exercise for me, for code that was already in my opinion perfectly adequate in both coding style and documentation (not to mention the fact that it is supplemented with extensive UML diagrams).

I see the point of coding standards and having a tool like Coder (which does its job of applying the rules well enough) , but as far as I am concerned - as one can see from my various recent issue reports for Coder - a number of the rules it is applying, in many cases derived from the official Drupal coding standards and documentation standards, are just plain annoyingly trivial, irrelevant, or verbose without any benefit,

Experienced OO developers don't typically document every single getter and setter.

One thing I find particularly inconvenient is to have to repeat documentation for getters and setters both in the method function description and in the @param or @return section. In many cases I would argue that one does not even need the function description if the meaning is clear in context.

The Drupal API documentation and comment standards currently state:

Every function, constant, class, interface, class member (function, property, constant), and file must be documented, even private class members.

Before my examples, and please without inviting an argument about the pros and cons of Agile, a quote from http://www.agilemodeling.com/faq.htm#HowMuchDocumentation:

2.8 How much documentation do I need to write?

Just enough to get the job done, and that's often far less than you need. Travel as light as possible and take an agile approach to documentation in general.

In the following (and yes I am fully aware that I am departing from the also painfully verbose recommendation that interfaces be suffixed by 'Interface') it is pretty clear what getName and setName do with barely any docs at all:

interface ITag extends ITagManager {
 
  /**
   * @return string
   */
  public function getName();
 
  /**
   * @param string $name
   * 
   * @return ITag
   */
  public function setName($name);

Gee I wonder what getName and setName do, or what $name is ?

And I wonder what is returned by the setter, is it 'this' ITag, or is it another ITag from a distant galaxy (after all, I might not be applying the convention of returning 'this') ?

Let's make it much clearer with more docs, instead of relying on the getter/setter patterns and conventions, that will add some enormous benefit and use my unpaid time well.

interface ITag extends ITagManager {
 
  /**
   * The name.
   *
   * @return string
   */
  public function getName();
 
  /**
   * Sets the name.
   *
   * @param string $name
   * 
   * @return ITag
   *  This.
   */
  public function setName($name);

Is it clearer if I add 'of the tag', for those who did not notice the name of the Interface, ITag ?

interface ITag extends ITagManager {
 
  /**
   * The name of the tag.
   *
   * @return string
   */
  public function getName();
 
  /**
   * Sets the name of the tag.
   *
   * @param string $name
   * 
   * @return ITag
   *  This.
   */
  public function setName($name);

Wow, that cleared it up for me.

What about that @return in the getter and that @param in the setter, I mean so far it leaves me wondering exactly what is being set and returned. After all, it only says the getter called getName() returns a 'string' and the setter accepts a 'string' called $name, it might not be a "name", it could be any string, it could be .. a type of marshmallow .. or an alien spaceship's call sign. Let's "fix" it:

interface ITag extends ITagManager {
 
  /**
   * The name of the tag.
   *
   * @return string
   *   The name of the tag.
   */
  public function getName();
 
  /**
   * Sets the name of the tag.
   *
   * @param string $name
   *   The name of the tag to set.
   * 
   * @return ITag
   *  This.
   */
  public function setName($name);

And now Coder is happy, for a while, not least because I used full stops above and removed excess whitespace my IDE introduced, too, and I did not use any (one or tow word) inline comments after code statements, and I did not use any inline comments to comment out code that does not start with a Capital (does code ever), or leave spaces after inline comments applied to code or brief tagging words like //TODO and //DEBUG (sorry, I mean "// TODO. " or at least '// DEBUG!' ), all very important things that add .. almost no value at all.

But I'm not happy, no no. I am just plain annoyed at having some more time of my life stolen (that nobody is ever going to give me back) doing something pointless of absolutely no additional benefit to anybody who has an ounce of common sense.

Proposal:

1. Please relax the rule on strict documentation of every part of every method, at least for OO getters and setters.

2. Tune Coder to detect getters and setters and not be strict about trivially obvious documentation.


As far as I am concerned (and nobody can claim I haven't taken it seriously, after all, I have devoted many days to it I would rather have used writing new code) the entire Coder and Drupal coding and documentation standards matter has gotten completely out of hand, and if it annoys me this much (a very experienced OO developer), it is going to turn a lot of other people off, too, and it will especially turn them off OO.

affects version: 
Coder 7.x-2.2
OO: Coding standards: permit CAPITALS_WITH_UNDERSCORES for static class variables

If you want me to push this to Drupal core: base: coding standards please just say so, but I want a record keyed to Coder because I would like the rule changed in Coder (assuming it is changed in the standards).

Example:

  /**
   * Tags that may not have children (are self-closing).
   * 
   * @see http://www.standardista.com/html5/xhtml-elements-their-parent-children-attributes-and-default-browser-presentation/
   * @var array
   */
  static public $TAGS_WITH_NO_CHILDREN = array(
    'br',
    'hr',
    'img',
    'base',
    'link',
    'meta',
    'area',
    'col',
    'param'
  );

Coder output:

ERROR   | Class property $TAGS_WITH_NO_CHILDREN should use lowerCamel
     |         | naming without underscores

Using CAPITALS_WITH_UNDERSCORES for static class variables that act as constants is a common convention in many OO languages, especially Java. Examples:

- http://java.about.com/od/javasyntax/a/nameconventions.htm

- http://www.appperfect.com/support/java-coding-rules/namingconvention.html

Please consider at least permitting this variation for static class variables in the Drupal coding standards (and thus in Coder).

affects version: 
Coder 7.x-2.2
OO: Documentation standards: documenting every constant "overkill" when context is clear.

The Drupal API documentation and comment standards currently state:

Every function, constant, class, interface, class member (function, property, constant), and file must be documented, even private class members.

Why should I invest time documenting these, are they otherwise too mysterious ?

class XHTML {
  const TABLE = 'table';
  const TR = 'tr';
  const TD = 'td';
  const TH = 'th';
  const A = 'a';
  const P = 'p';
  const B = 'b';
  const STRONG = 'strong';
  const I = 'i';
  const EM = 'em';
  const DIV = 'div';
  const IMG = 'img';
  const SPAN = 'span';
  const HR = 'hr';
  const BR = 'br';
  const BLOCKQUOTE = 'blockquote';
  const OL = 'ol';
  const UL = 'ul';
  const DL = 'dl';
}

Where is the "value add" in doing this over and over:

  /**
   * The XHTML DL tag name constant.
   * @var
   */
  const DL = 'dl';
affects version: 
Coder 7.x-2.2
Coder does not accept function parameter indicators in @see (but API module does)

The following @see references to functions with parameter indicators are both accepted fine by the API module:

/**
 * ..
 * 
 * @see system_settings_form(array $form)
 * 
 * @see ooe_form_admin(array $form, array &$form_state)
 * ..
 */

The API module generates for the above a nice link to each recognised function following be the parameter indicators as plain text:

- system_settings_form(array $form)

- ooe_form_admin(array $form, array &$form_state)

But Coder generates for these the following error report:

ERROR | The @see reference should not contain any additional text

The following (just showing the array parameter type, leave out the parameter variable) for some reason does not trip Coder:

* @see system_settings_form(array)

The following are also accepted by Coder:

   * @see system_settings_form()
   * 
   * @see ooe_form_admin()
   *

But these do not include the sometimes very useful parameter indicators in the API output, they just give:

- system_settings_form()

- ooe_form_admin()

I would like support for such indicators of function parameters as shown at the top.

The Drupal doc standards for @see currently states:

Drupal standards: Each @see reference is on its own line, with no additional text beyond the item being referenced.

I see no reason why 'the item being referenced' can't be a complete method or function signature, and it could be identified as a function name followed by something in () parentheses.

affects version: 
Coder 7.x-2.2
Advanced feature idea: Coder strict mode (applies all rules) and user selectable rule switches, together with Coder configuration file for submission with a module

This may take some work, however long term I think this is a good idea. I have looked through the Coder docs and I am not sure whether this functionality exists in an integrated form yet.

- Coder has a configuration file with a strict mode switch and with other switches for rule preferences that depart from strict mode.

- Projects that have had Coder applied to them also make available the Coder configuration file they are known to completely pass.

- Projects that pass Coder strict mode get a special indicator, say a Coder Strict icon, on their project home page.

This would enable people to depart from Drupal strict comment and coding standards in a controlled way, while still applying the majority of Coder rules.

Thus, I could say have a Coder configuration file that matches my own recipe for PHP that is more amenable to reverse engineering to UML, and does not apply rules such as this one: 'OO: Coder complains about camel caps (camelCase) argument to setter method in Class.'

Projects hoping to move from the sandbox can, during application for full project rights, make available their Coder config file with the strict mode switch and other rule switches via the repository.

PHPCBF: How list available sniffs within installed coding standards packages

I am trying to apply specific sniffs/rules after: https://github.com/squizlabs/PHP_CodeSniffer/wiki/Fixing-Errors-Automati...

I can see how to list the available coding standard packages, but not the sniffs within each package.

$ phpcbf --version
PHP_CodeSniffer version 2.3.0
$ phpcbf -h
Usage: phpcbf [-nwli] [-d key[=value]]
    [--standard=<standard>] [--sniffs=<sniffs>] [--suffix=<suffix>]
    [--severity=<severity>] [--error-severity=<severity>] [--warning-severity=<severity>]
    [--tab-width=<tabWidth>] [--encoding=<encoding>]
    [--extensions=<extensions>] [--ignore=<patterns>] <file> ...
        -n            Do not fix warnings (shortcut for --warning-severity=0)
        -w            Fix both warnings and errors (on by default)
        -l            Local directory only, no recursion
        -i            Show a list of installed coding standards
        -d            Set the [key] php.ini value to [value] or [true] if value is omitted
        --help        Print this help message
        --version     Print version information
        --no-patch    Do not make use of the "diff" or "patch" programs
        <file>        One or more files and/or directories to fix
        <encoding>    The encoding of the files being fixed (default is iso-8859-1)
        <extensions>  A comma separated list of file extensions to fix
                      (extension filtering only valid when checking a directory)
                      The type of the file can be specified using: ext/type
                      e.g., module/php,es/js
        <patterns>    A comma separated list of patterns to ignore files and directories
        <sniffs>      A comma separated list of sniff codes to limit the fixes to
                      (all sniffs must be part of the specified standard)
        <severity>    The minimum severity required to fix an error or warning
        <standard>    The name or path of the coding standard to use
        <suffix>      Write modified files to a filename using this suffix
                      ("diff" and "patch" are not used in this mode)
        <tabWidth>    The number of spaces each tab represents
$ phpcbf -i
The installed coding standards are MySource, PEAR, PHPCS, PSR1, PSR2, Squiz and Zend

How can I list the sniffs within each coding standard package ?


From @klausi https://www.drupal.org/node/2462841#comment-9792371:

I think there is no way to get a list of all possible sniffs that a standard has, but you can execute phpcs with the "-s" option. It will show you the sniff code, example:

$ phpcs --standard=Drupal -s good2.php 
FILE: /home/klausi/workspace/coder/good2.php
----------------------------------------------------------------------
FOUND 2 ERRORS AFFECTING 2 LINES
----------------------------------------------------------------------
 14 | ERROR | [x] Expected "int" but found "integer" for parameter
    |       |     type
    |       |     (Drupal.Commenting.FunctionComment.IncorrectParamVarName)
 17 | ERROR | [x] Whitespace found at end of line
    |       |     (Squiz.WhiteSpace.SuperfluousWhitespace.EndLine)
----------------------------------------------------------------------
PHPCBF CAN FIX THE 2 MARKED SNIFF VIOLATIONS AUTOMATICALLY
----------------------------------------------------------------------

Then you should e able to fix trailing white spaces with:

$ phpcbf --standard=Drupal --sniffs=Squiz.WhiteSpace.SuperfluousWhitespace good2.php

Edit: that worked for me now, you need to use "--sniffs", not "--sniff".

Remove requirement that no blank line follow an inline comment?

I am reopening this issue merely to be pointed in the correct direction where I can contest both the coding standards rule and the sniff.

Moved that portion of the sniff to DrupalPractice now and committed this http://drupalcode.org/project/coder.git/commit/920166d

If you moved the sniff to DrupalPractice where should I raise and issue to further contest this rule ?
Also, on accessing http://drupalcode.org/project/coder.git/commit/920166d I got a 500 Internal Server Error (may be intermittent).

Why I don't like this rule

I do not like this Coding Standard recommendation:

"Comments should be on a separate line immediately before the code line or block they reference."

There are at least three main cases:

The 1st one is already mentioned, comments such as intermediary // @todo statements.

2nd: Comments have been used in many languages for decades to describe general aspects of coding without referring to one particular following line/block of code. I appreciate this is easily abused, but it is simply not the case that every comment has to or should refer to a following line of code. Sometimes "meta comments" refer to multiple blocks of following code (each of which then does have a single line header comment), and this rule makes this impossible to clearly indicate.

3rd: This is my major complaint about this standard's rule and the sniff. It is a common practice (very widely used in my experience, and a favourite of mine) to have 2 different kinds of comments BEFORE and AFTER the code. A brief comment BEFORE says WHAT the code to follow does; the comment AFTER the code remarks on special conditions, problems, more complex coding issues, remarks on alternative strategies etc., it is commentary about HOW it has been done.

BEFORE = WHAT
AFTER = HOW

// This code will do something: WHAT.
$code;
$code;
$code;
$code;
// Further comments about the code: HOW. Possible issues,
// alternative strategies, a nice place for @todos, 
// deeper developer remarks.

Placing such complex comments before the code block makes harder to read,
and it also mixes up the description of WHAT the code is to do with HOW it did it.

PAReview is spitting the dummy massively on one of my projects that
deliberately uses this coding style for educational purposes:

http://pareview.sh/pareview/httpgitdrupalorgsandboxwebel2120905git

http://dupal7demo.webel.com.au/module/ooe

It is a huge task for me to go through that large project just for this rule.

@link @endlink alone on 2nd line gives 'There must be exactly one blank line before the tags in a doc comment'

This trips Coder:

/**
 * Default implementation of a menu item (without a page or form controller).
 *
 * UML:
 * @link http://drupal7demo.webel.com.au/node/1017 DefaultMenuItem @endlink.
 *

With error:

There must be exactly one blank line before the tags in the doc comment.

This (having the @link after some other text on the same line) avoids the above error, but the line turns out to be too long:

/**
 * Default implementation of a menu item (without a page or form controller).
 *
 * UML: @link http://drupal7demo.webel.com.au/node/1017 DefaultMenuItem @endlink.
 *
Line exceeds 80 characters; contains 81 characters.

This problem occurs a lot for me, especially because links are often long.

It should be possible to have a @link @endlink on a line alone and over 80 characters.


From @klausi https://www.drupal.org/node/2463397#comment-9792317:

Version: 8.x-2.1 » 8.x-2.x-dev
Status: Active » Closed (duplicate)
This was fixed with #2463401: @link @endlink starting 2nd line causes 'Doc comment long description must end with a full stop'.

affects version: 
8.x-2.1
fixed in version: 
8.x-2.x-dev 2015-04-05
@link @endlink starting 2nd line causes 'Doc comment long description must end with a full stop'

This docblock trips Coder:

  /**
   * Sets the access callback to a string representing a callback function.
   *
   * For forcing it to a boolean TRUE or FALSE please use
   * @link IMenuItem::forceAccessCallbackTRUE @endlink() OR
   * @link IMenuItem::forceAccessCallbackFALSE @endlink().
   *

With error:

Doc comment long description must end with a full stop.

In the above the () brackets after the @endlink() are just to make it look nicer (like a function) when passed through the API doc generator, they make no difference.

Same happens for:

  /**
   * Sets the access callback to a string representing a callback function.
   *
   * For forcing it to a boolean TRUE or FALSE please use
   * @link IMenuItem::forceAccessCallbackTRUE @endlink OR
   * @link IMenuItem::forceAccessCallbackFALSE @endlink.
   *

Clearly this long comment description does end with a full stop, so this is a bug.

This seems to work (not having @link start the line):

  /**
   * Sets the access callback to a string representing a callback function.
   *
   * For forcing it to a boolean TRUE or FALSE please
   * use @link IMenuItem::forceAccessCallbackTRUE @endlink
   * OR @link IMenuItem::forceAccessCallbackFALSE @endlink.

It should definitely be permitted to have @link at the start of a comment line, as explained also at (https://www.drupal.org/node/2463397) to permit use of long URLs in @link statements.


@klausi wrote https://www.drupal.org/node/2463401#comment-9792287:

Version: 8.x-2.1 » 8.x-2.x-dev
Status: Active » Fixed
Committed a fix, thanks for reporting!

affects version: 
8.x-2.1
fixed in version: 
8.x-2.x-dev
Request shortcuts for @codingStandardsIgnoreStart/@codingStandardsIgnoreEnd

The @codingStandardsIgnoreStart/End pair are very long and tedious if used often.

Example of usage to avoid 'There must be no blank line following and inline comment' error.

  /**
   * An array of arguments to pass to the page callback.
   *
   * @var string[]
   */
  protected $pageArguments;
  // @codingStandardsIgnoreStart
  // NB: @var string[] not caught by PEAR PHP_UML !
  // @codingStandardsIgnoreEnd

Please introduce a shortcut. Some ideas.

Extremely compact:

// @csis
// ...
// @csie

Quite compact:

// @csiStart
// ...
// @csiEnd
// @csIgnoreStart
// ...
// @csIgnoreEnd

Not sure whether this is possible, use bracket in annotation:

// @csi{
// ...
// @csi}
// @csi[
// ...
// @csi]
affects version: 
8.x-2.1
Permit exclamation mark ! punctuation at end of parameter comment

It is common practice to use exclamation marks to indicate special conditions on parameters.

This should be permitted without giving the error:

Parameter comment must end with a full stop.

Simple case:

  /**
   * Supplies a basic menu item product.
   *
   * @param string $title
   *   Required !
   * @param string $path
   *   Required !
   *
   * @return \Drupal\ooe\Menu\IMenuItem
   *   A new menu item.
   */
  public function newMenuItem($title, $path);

More complex case:

  /**
   * Add a validation handler to a form.
   *
   * @param array $form
   *   A Drupal form array.
   * @param string $validatorMethodName
   *   The name of a _static_ validator method (only) with signature
   *   ($form, &$form_state); DO NOT include the class name !
   */
  protected function addValidateHandler(array &$form, $validatorMethodName) {

2015-04-05 From @klausi https://www.drupal.org/node/2463425#comment-9792179:

Committed a fix to allow "!" and "?", thanks for reporting!

affects version: 
8.x-2.1
fixed in version: 
8.x-2.x-dev (2015-04-05)
Interface methods without explicit public visibility modifier should not trigger 'ERROR Visibility must be declared on method'

Coder currently trips on Interface methods that are not explicitly declared public:

ERROR Visibility must be declared on method.

There is no need for this on Interface methods.

From http://php.net/manual/en/language.oop5.visibility.php:

Methods declared without any explicit visibility keyword are defined as public.

In various discussion of interfaces in PHP, it is often remarked that they should only have public methods (or more formally, as in UML, Operations). From http://php.net/manual/en/language.oop5.interfaces.php:

All methods declared in an interface must be public; this is the nature of an interface.

But notice it says they must only be public, not that they must be explicitly declared public.

In Java it has long been the tradition to not explicitly declare the visibility of Interface operations.

PHP handles interfaces without explicit public visibility modifiers fine, it should not cause a Coder error, and it should not be required by the Drupal Coding Standards.

affects version: 
8.x-2.1
@link @endlink starting 2nd line causes 'Parameter tags must be defined first in a doc comment' in methods

The following trips Coder:

  /**
   * Sets the title of the menu.
   *
   * Visit also:
   * @link https://www.drupal.org/node/323101 Strings at well-known places: built-in menus, .. @endlink
   *
   * @param string $title
   *  'The untranslated title of the menu item.
   *
   * @return IMenuItem
   *   This.
   */
  public function setTitle($title);

With this error:

Parameter tags must be defined first in a doc comment

Why shouldn't one be allowed to have a @link @endlink inline (or on its own line between other text) in a method description ?

affects version: 
8.x-2.1
Coding Standard: Please remove the requirement that no blank line follow an inline comment

This is spawned from the Coder issue queue [#2159253].

It is related to this statement under the current Drupal Coding Standards:

Drupal standards for in-line code comments

Non-header or in-line comments are strongly encouraged. A general rule of thumb is that if you look at a section of code and think "Wow, I don't want to try and describe that", you need to comment it before you forget how it works. Comments should be on a separate line immediately before the code line or block they reference.

In the original TravisGarden proposed:

'... that it is overly restrictive--that there are valid use cases for an inline comment with a blank line beneath it.'

I agree fully with this, and I provide numerous examples here below where inline comments are sensibly used without referring to a line of code immediately below it.

Most of TravisGarden's examples involved use of @todo statements, such as this example:

For example, suppose I want to leave a @todo to add a block of code in the future:

do_something();
 
// @todo This would be a good place to add logging.
 
do_something_else();

The text format here strips the line breaks from my code sample, but supposing that the @todo is not directly related to the do_something_else() function, it seems misleading to put it right above it as if it described it. Doubtless numerous other cases can be imagined which I will not belabor here.

Many other examples of using inline comments BELOW code they refer to or independent of a specific line of code

There are at least three main cases I have identified:

The 1st one is already mentioned, comments such as intermediary // @todo statements.

2nd: Comments have been used in many languages for decades to describe general aspects of coding without referring to one particular following line/block of code. I appreciate this is easily abused, but it is simply not the case that every comment has to or should refer to a following line of code. Sometimes "meta comments" refer to multiple blocks of following code (each of which then does have a single line header comment), and this rule makes this impossible to clearly indicate.

3rd: This is my major complaint about this standard's rule and the sniff. It is a common practice (very widely used in my experience, and a favourite of mine) to have 2 different kinds of inline comments, for distinct use BEFORE and AFTER the code. A brief comment BEFORE says WHAT the code to follow does; the comment AFTER the code remarks on special conditions, problems, more complex coding issues, remarks on alternative strategies etc., it is commentary about HOW it has been done.

BEFORE = WHAT
AFTER = HOW

// This code will do something: WHAT.
$code;
$code;
$code;
$code;
// Further comments about the code: HOW. Possible issues,
// alternative strategies, a nice place for @todos, 
// deeper developer remarks.

Placing such complex comments before the code block makes harder to read,
and it also mixes up the description of WHAT the code is to do with HOW it did it.

Crucially, somebody trying to read inline comments about HOW the coding was done - and especially about special conditions, requirements, or choices - can't understand the remarks until the code has been read ! They therefore belong after the code, and they are clearly of a different nature to the usually brief comments that are used before the code.

PAReview is spitting the dummy massively on one of my projects that
deliberately uses this coding style for educational purposes:

http://pareview.sh/pareview/httpgitdrupalorgsandboxwebel2120905git

http://dupal7demo.webel.com.au/module/ooe

It is a huge task for me to go through that large project just for this rule.

Another example:

class AdminMenuItem extends FormMenuItem {
 
  /**
   * Access permissions "constant".
   *
   * @var string
   */
  private static $ACCESS = array('access administration pages');
  // NB: can't use const with array definition:
  // http://stackoverflow.com/questions/11184469/php-use-array-as-class-constant

(And yes I am aware this breaks some other coding standard recommendations I don't like.)

I insist that having for example:

$some_code;
$more_code;
 // @todo Remark on the above code and what is still todo.

is a very common and very useful practice. It should be allowed (not least where the Coder rule also discourages comments immediately after code on the same line).

And another example where one might sensibly use an inline comment either on the same line as (after) the code (apparently not allowed by Coder 8.x-2.1) or on the next line (also apparently not allowed by Coder 8.x-2.1):

  public function __construct($module) {
    // Not protected ! Because parent requires public.
 
    parent::__construct($module);

In general, and not just for the @todo case, this rule as it apparently still stands in Coder 8.x-2.1 is causing me a massive headache.

Finally, I am not just talking about intermittent remarks that would disappear in "complete" code, or final shiny commits; I am talking about inline comments that are of lasting value to me as a developers and to other developers reading my code, comments that are useful completely alone without immediate reference to a specific line of code (comments that belong to a function as a whole yet are sensible placed between code blocks) and comments that sensibly follow specific code lines.


@klausi wrote at Coder issue: [#2159253]

Comments that do not belong to any line a rare.

I disagree. Not only are there lots of sensibly used inline comments in my code that do not belong to any line, there are certain types of inline comments that do "belong" to a line, but they are best placed below the code they remark on. I in fact strongly encourage the practice, instead of having lots of technical comments preceding code, which comments make no sense until one has read that code.


This Drupal Coding Standards remark is revealing:

A general rule of thumb is that if you look at a section of code and think
"Wow, I don't want to try and describe that",
you need to comment it before you forget how it works.

This is why I recommend using inline comments that say WHAT some following code is about to do before that code, and distinct inline comments that say HOW the code did it or WHY it did it that way after the code.

I can think of few thinks that are harder to read than inline comments that explain in detail HOW and/or WHY code has been written a certain way (or remarks about special circumstances) before one has even had the chance to read the code that those comments are remarking on.

There is great value and wisdom in my recommendation.

Incorrect report 'Separate the @file and @link sections by a blank line.'

The following is as far as I can tell incorrectly reporting:

FILE: .../ooe/ooe.module
----------------------------------------------------------------------
FOUND 1 ERROR AFFECTING 1 LINE
----------------------------------------------------------------------
 22 | ERROR | [x] Separate the @file and @link sections by a blank line.
----------------------------------------------------------------------
/**
 * @file
 * The non-OO module hook file for the Object-Oriented Examples (OOE) project.
 *
 * An educational tutorial module that demonstrates an Object-Oriented
 * bridge between Drupal7 core's contributed module API and a fully
 * Object-Oriented space. OOE stands for Object-Oriented Examples.
 *
 * OOE also progressively demonstrates "one of each" (OOE) of the
 * capabilities of Drupal contributed modules using object-oriented PHP
 * and the special bridge between Drupal core and a full OO coding space.
 *
 * OOE may also be taken to mean "Object Oriented Examples",
 * because it demonstrates object-oriented techniques and promotes
 * a move towards true object-orientation in future Drupal,
 * and already offers a form of pure OO module development API.
 *
 * A comprehensive guide with OOE running live and a detailed discussion
 * with links to many object-oriented examples is available at:
 * @link http://drupal7demo.webel.com.au/module/ooe Webel Drupal7 demo: OOE @endlink.
 *
 * ...

Another similar example. This causes Coder 8.x-2.x-dev to trip with:

 Separate the @todo and @link sections by a blank line.
/**
 * Abstract implementation of those parts of a block view
 * typically common to all implementations.
 *
 * @todo Consider forcing use of @link IRender @endlink objects
 * instead of permitting any render array return values.
 *
 * UML:
 * @link http://drupal7demo.webel.com.au/node/1128 AbstractBlockView @endlink.
 */

But placing the @todo lower in the docblock prevents the error report:

/**
 * Abstract implementation of those parts of a block view
 * typically common to all implementations.
 *
 * UML:
 * @link http://drupal7demo.webel.com.au/node/1128 AbstractBlockView @endlink.
 *
 * @todo Consider forcing use of @link IRender @endlink objects
 * instead of permitting any render array return values.
 */

@klausi https://www.drupal.org/node/2465729#comment-9796493 (2015-04-07):

Committed a fix, thanks for reporting!
klausi committed 5e0a16e on 8.x-2.x

affects version: 
8.x-2.x-dev
fixed in version: 
8.x-2.x-dev (2015-04-07)
Permit long URL in @todo comment in docblock

It is often useful to include URL references as shown below in @todo statements in docblock comments (in the example shown below this is clearly for "work in progress" code).

However, when such long URLs they are included directly as shown here it gives the error:

119 | WARNING | Line exceeds 80 characters; contains 87 characters
  /**
   * Sets the CSS style of this.
   *
   * @todo check whether valid style, no help at
   * http://au2.php.net/manual/en/filter.filters.validate.php
   *
   * @todo Perhaps CSS regex checker: CSS2 here:
   * http://stackoverflow.com/questions/21223418/check-string-for-valid-css-using-regex
   *
   * @param string $style
   *   The CSS style of this.
   *
   * @return ITagManager
   *   This.
   */
  public function setCssStyle($style) {

Where this URL alone contains 83 characters: http://stackoverflow.com/questions/21223418/check-string-for-valid-css-u...

If I try instead this:

   * @todo Perhaps CSS regex checker: CSS2 here:
   * @link http://stackoverflow.com/questions/21223418/check-string-for-valid-css-using-regex @endlink

I get this error:

ERROR: Separate the @todo and @link sections by a blank line.

I have reported this initially as a bug; if there is another way of including URLs in @todo comments in docblocks please advise.

affects version: 
8.x-2.x-dev
Permit concat operator at end of line

The following gives this error 3 times:

Concat operator must be surrounded by a single space
      throw new \Exception('$visibility must be one of (' .
      BLOCK_VISIBILITY_NOTLISTED . ', ' .
      BLOCK_VISIBILITY_LISTED . ', ' .
      BLOCK_VISIBILITY_PHP . '), got(' . $visibility . ')'
      );

Placing them all on one very long line prevents the Coder error report, but is far less readable:

      throw new \Exception('$visibility must be one of (' . BLOCK_VISIBILITY_NOTLISTED . ', ' . BLOCK_VISIBILITY_LISTED . ', ' . BLOCK_VISIBILITY_PHP . '), got(' . $visibility . ')'
      );

May I suggest that having a newline after a concat operator plays much the same role as a space, makes in many cases for more readable code, and should be permitted, as long as that concat operator as a space before it as shown.

(I appreciate that some circumstances like this are better handled with placeholders.)

affects version: 
8.x-2.x-dev
Incorrect report 'Missing parameter type' when no suitable type available

Case: $node parameter. Neither 'stdClass' nor 'object' are accepted a types (see also discussion/arguments at [#595084}). Leaving off the type hint parameter gives ERROR:

Missing parameter type.

But for $node there is currently AFAIK no recommended type (and certainly no obvious interface type in D7).

But according to the Drupal Documentation Standards no type is required: https://www.drupal.org/coding-standards/docs#param:

The @param tag is followed by an optional data type indicator, then the variable name of the parameter, and then a newline.

There are many reasons that insisting on a type hint is nevertheless well advised, but since Drupal7 is not sufficiently object-oriented and does not fully adopt "Design By Contract" against Interfaces, it is not always clear what one should use as a type hint. As an avid fan of full object-orientation and graphical software engineering with Unified Modeling Language (UML), I am certainly in favour of always using type hints, which are handled quite well (mostly) by PEAR:PHP_UML. See also discussion/debate/arguments Documentation standard for @param and @return data types.

But as long as the official Drupal Coding Standards don't require a type, and as long as it is not clear (thanks to Drupal7's lack of decent OOP) what type one should choose, I do not think Coder should insist on a type hint.

Another case: one should here be able to omit the type of the $flag handler.
<?
/**
* Whether the given flag is applicable to the given bundle and entity type.
*
* @param $flag
* The flag handler to check.
* @param string $entity_type
* The entity type to check against.
* @param string $bundle
* The bundle to check against.
*
* @return bool
* Whether the given flag is applicable to the given bundle and entity type.
*/
function _flagplus_flag_may_apply($flag, $entity_type, $bundle) {
?>


https://www.drupal.org/node/2466469#comment-9797397

More cases: with stdClass:

/**
 * A render array with flagplus banners (if any applicable).
 *
 * @param stdClass $node
 *   The node to add banners to.
 *
 * @return array
 *   A render array with flagplus banners (if any applicable).
 */
function _flagplus_banners(stdClass $node) {
/>
 
Gives Coder error:
[geshifilter-code]&#10;Expected &#039;object&#039; but found &#039;stdClass&#039; for parameter type.&#10;[/geshifilter-code]
 
 
Using 'object' for both the @param type and the function signature type hint fails:
<?php
/**
 * A render array with flagplus banners (if any applicable).
 *
 * @param object $node
 *   The node to add banners to.
 *
 * @return array
 *   A render array with flagplus banners (if any applicable).
 */
function _flagplus_banners(object $node) {
Unkown type hint "object" found for $node.

But leaving 'object' off the actual type hint, but on the @param type, works (passed Coder without ERROR):

/**
 * A render array with flagplus banners (if any applicable).
 *
 * @param object $node
 *   The node to add banners to.
 *
 * @return array
 *   A render array with flagplus banners (if any applicable).
 */
function _flagplus_banners($node) {

(All of which makes me cry with desire for full OOP and Java under model-driven development with graphical UML support more than I can express. Drupal7 is primitive. W.r.t. Drupal Code of Contact. It can't be an insult to anybody if I simply state that nearly the entire Drupal effort is primitive as far as OOP is concerned.)

affects version: 
8.x-2.x-dev (2015-04-07)
False report for stdClass type hint: Expected "object" but found "stdClass" for parameter type

Example:

  /**
   * If banners decorator mode is on, decorates the node content with banners.
   *
   * @param stdClass $node
   *   The node to decorate.
   * @param string $view_mode
   *   The node display mode.
   */
  static public function addBannersDecoratorToNode(stdClass &$node, $view_mode) {

Gives Coder error report:

 Expected "object" but found "stdClass" for parameter type

In fact if you use 'object' as the type hint with PHP5.3 as far as I can tell it crashes:

Recoverable fatal error: Argument 1 passed to Drupal\flagplus\banner\BannerHelper::addBannersDecoratorToNode() must be an instance of Drupal\flagplus\banner\object, instance of stdClass given
affects version: 
8.x-2.x-dev
Visit also