False positives when checking for code and comment standards

When using automated tools to improve code quality, it sometimes happens that warnings are shown while the code is correct or hard to fix. Depending on your setup, these warning can prevent committing your code and/or setting up a test/acceptance environment.

I came across this issue when adding multi-line @todo comment. Like the example below:

// @todo This is a multi-line todo comment that adheres to Drupal's comments
//   convention, but currently is marked as not when running phpcs.

When using drupal/coder to check my implementations against Drupal's coding standards, it falsely reports that the code fragment above is incorrect (i.e., two extra spaces are added in the begin of the second comment line). However, the @todo comment standard encourages these extra spaces, which allows text editors to correctly apply seperate syntax highlighting for (multi-line) @todo instructions.

Since the fragment is correct, a simple quick-fix is to instruct phpcs to ignore these lines:

// phpcs:disable
// @todo To overcome the incorrect message that the multi-line todo comment is
//   incorrect, just surround it with phpcs:disable and phpcs:enable.
// phpcs:enable

Though the quick-fix is simple and @todo comments should be resolved, it is still of course a bug/missing feature of the drupal/coder project that not all (correct) ways you can write multi-line @todo comments are supported. In general this simple feature of phpcs can be used when there are good reasons you can't, at that moment, comply to the coding standards.

Category
Drupal
Coding Standards
Quality Assurance
PHP_CodeSniffer

Plain text

  • No HTML tags allowed.
  • Lines and paragraphs break automatically.
  • Web page addresses and email addresses turn into links automatically.