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, this warning can prevent committing your code or setting up a test/acceptance environment.
I came across this issue when adding a 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 at the beginning of the second comment line). However, the @todo comment standard encourages these additional spaces, which allows text editors to correctly apply separate 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 with the coding standards.
Category
Drupal
Coding Standards
Quality Assurance
PHP_CodeSniffer
Comments1
Nice
Nice