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.
Comments1
Nice
Nice