[policy] Relax rule for inline Comments: 'Comments may not appear after statements'

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.

Seriously, this rule is just plain annoying, it has to go.

Here is another example. I am calling an operation of a class MenuTabs:

  /**
   * Makes a new tab menuitem with the given page controller and title.
   * 
   * @param \Drupal\ooe\Page\IPageController $pageController
   *   The page controller for the tab menu item.
   * @param string $title
   *   The title of the menu item
   * @param bool $isDefault
   *   Whether this is a default.
   * 
   * @return \Drupal\ooe\Page\IPageMenuItem
   *   The new tab menu item.
   * @throws \Exception
   *   If $isDefault is not a boolean.
   */
  protected function makeTabMenuItem(IPageController $pageController, $title, $isDefault = false) {
..

In the case where fixed values are passed as parameters it is handy to use trailing inline comments:

$this->menuItemDefault = $this->makeTabMenuItem(
        $this->pageControllerBase,
        NULL, // $title: Rely on default tab title assignment by item count
        TRUE // $isDefault
);

It's concise and clear. The alternative is to define temporary local parameter value holders,
or to have the comments on separate lines after each value so Coder does not complain.

And another useful example of a token/keyword one can search on. DEBUG statements with inline comment marker:

dpm($var,'var'); // DEBUG

And another case: asserting that a line is right (a good idea ok) with an exclamation mark:

    $n = count($this->menuItems); // !

For what it's worth, I don't like having to leave the space after //, I prefer:

    $n = count($this->menuItems); //!

@klausi

I appreciate your contribution but please do not simply close my issues this way, you haven't addressed the matter at all:

I think this sniff is fine as is.

Absolutely not. You haven't addressed for example the matter of filtering on keywords on inline comments after a piece of code like // DEBUG, // TODO, // CHECK. In fact you haven't addressed any of the examples I've given (and nor does putting the comment before or after the code line).

My reports are carefully written and well argued with many examples and are possibly of interest to others, I don't mind if you delay attending to them, or offer a different opinion, but simply closing them because you don't agree is not acceptable.

@davidwbaratt Just a quick reply to say that I am following all coding standards and Coder related tickets, but I am not offering any further input at the moment. Thanks for your time in considering this and other coding standards related issue reports.

@tizzo suggested 'I think you misunderstand the recommendation.'

Implied telepathy aside, I don't misunderstand it, I understand it fully. I just don't like it as the only option.

There are appropriate and different acceptable usages of comments:

1. Before a line of code.
2. At the end of a line of on the same line (especially for briefly "tagging" IDE-searchable matters).
3. After a line of code.

After over 35 year of coding I think I've seen every acceptable variant by now.

The Drupal coding standard is unnecessarily limiting (and w.r.t. 2. above not particularly IDE friendly).