Coder - alter requirements about no blank line following an inline comment

The coding standards say "Comments should be on a separate line immediately before the code line or block they reference.", I think that was the reason this check was introduced. https://drupal.org/node/1354#inline

That will apply to at least 95% of inline comments, but you are right: there can be some rare cases where the comment does not reference any code and is merely a placeholder.

So we could make an exception for "// @todo" comments? Can we come up with other examples?

I think the check for just a // @todo might be overly restrictive. As is the sniff for no blank lines following a comment.

The standard of "Comments should be on a separate line immediately before the code line or block they reference." implies that a comment referencing code should come on the line immediately preceding it. It probably should not be assumed to mean the reverse, that a comment must always be accompanied a specific line of code.

@swirt: the problem is that people did that wrong all the time, comments flying around where it was not immediately clear where they actually belong to. Comments that do not belong to any line a rare.

I'm using this sniff for project applications where this matters, so what we could do is move this sniff to the DrupalPractice sniffs which are used for project applications as well.

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

Thanks!

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.

@klausi About a year ago you said (as fix remark):

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

I found this https://github.com/klausi/drupalpractice, where it says:

DrupalPractice has been merged into Coder, please use that instead.

Where may I contest 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).

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.

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);

@TravisGarden. I created a detailed Drupal Technical Working Group task issue: #2464123: Remove the requirement that no blank line follow an inline comment.

But please do not close this issue here yet, it still needs to be tracked against Coder by Coder version.

@klausi wrote:

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.

Just for info I have created #2916000: Blank line after comment is reported by both Drupal and DrupalPractice

Adding related issue. It seems from #6 that the sniff was moved to DrupalPractice but not deleted from the Drupal standard.

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.

I double strongly discourage this practice. Comments should never be put after the section of code they describe. The examples given above are very confusing to read.

Postponed - pending the outcome of #2464123: Remove the requirement that no blank line follow an inline comment