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