Problem/Motivation

We skip coding standards warnings in a number of files with @codingStandardsIgnoreFile.

From https://github.com/squizlabs/PHP_CodeSniffer/wiki/Advanced-Usage#ignorin...

Before PHP_CodeSniffer version 3.2.0, use // @codingStandardsIgnoreFile instead of // phpcs:ignoreFile. The @codingStandards syntax is deprecated and will be removed in PHP_CodeSniffer version 4.0.

Coder currently depends on PHPCS 3.5.6 so we can do this now prior to the next major version bump of PHPCS.

Steps to reproduce

Proposed resolution

Replace the comments as suggested.

Remaining tasks

Consider whether we should really ignore all sniffs for each file with phpcs:ignoreFile, or only disable some sniffs with phpcs:disable.

User interface changes

API changes

Data model changes

Release notes snippet

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

longwave created an issue. See original summary.

longwave’s picture

Issue summary: View changes
quietone’s picture

Made with

grep -r @codingStandardsIgnoreFile core | awk -F: '{print $1}' | xargs sed -i 's/@codingStandardsIgnoreFile/phpcs:ignoreFile/'
claudiu.cristea’s picture

Status: Active » Needs review
quietone’s picture

And run the same command on sites directory.

longwave’s picture

Title: Replace @codingStandardsIgnoreFile with phpcs:ignoreFile » Replace @codingStandards comments with phpcs: comments
Status: Needs review » Needs work

Didn't spot these initially either; while we are here I guess we should change them too for consistency.

These need to become phpcs:ignore, phpcs:disable or phpcs:enable as appropriate.

core/modules/block/src/Plugin/migrate/process/BlockVisibility.php
58:  // @codingStandardsIgnoreLine

core/modules/migrate/src/Plugin/migrate/process/MigrationLookup.php
148:  // @codingStandardsIgnoreLine

core/modules/migrate/src/Plugin/migrate/process/MenuLinkParent.php
107:  // @codingStandardsIgnoreLine

core/tests/Drupal/KernelTests/Core/Theme/TwigMarkupInterfaceTest.php
48:      // @codingStandardsIgnoreStart
52:      // @codingStandardsIgnoreEnd

core/tests/Drupal/Tests/ComposerIntegrationTest.php
208:  // @codingStandardsIgnoreStart
252:  // @codingStandardsIgnoreEnd

core/lib/Drupal/Core/TypedData/Validation/ExecutionContextFactory.php
14: * @codingStandardsIgnoreStart

core/lib/Drupal/Core/TypedData/Validation/ConstraintViolationBuilder.php
17: * @codingStandardsIgnoreStart

core/modules/jsonapi/tests/src/Functional/MediaTest.php
345:  // @codingStandardsIgnoreStart
354:  // @codingStandardsIgnoreEnd
quietone’s picture

Status: Needs work » Needs review
FileSize
7.49 KB
46.47 KB

Testing locally and found that some of these file no longer need to ignore lines so this is not a one for one replacement.

longwave’s picture

Status: Needs review » Needs work

Comments below might be a bit of scope creep but I think better to fix them here than open lots of new issues for these tiny little changes.

  1. +++ b/core/lib/Drupal/Core/TypedData/Validation/ExecutionContextFactory.php
    @@ -33,8 +31,10 @@ class ExecutionContextFactory implements ExecutionContextFactoryInterface {
    +  // phpcs:disable
       public function __construct(TranslatorInterface $translator, $translationDomain = null)
       {
    +  // phpcs:enable
    

    I think we should just fix the coding standards issues on these lines.

  2. +++ b/core/lib/Drupal/Core/TypedData/Validation/ExecutionContextFactory.php
    @@ -43,6 +43,7 @@ public function __construct(TranslatorInterface $translator, $translationDomain
       public function createContext(ValidatorInterface $validator, $root)
    +  // phpcs:ignore
       {
    

    And here.

  3. +++ b/core/modules/block/src/Plugin/migrate/process/BlockVisibility.php
    @@ -55,7 +55,7 @@ class BlockVisibility extends ProcessPluginBase implements ContainerFactoryPlugi
    -  // @codingStandardsIgnoreLine
    +  // phpcs:ignore
       public function __construct(array $configuration, $plugin_id, $plugin_definition, ModuleHandlerInterface $module_handler, MigrateLookupInterface $migrate_lookup) {
    

    What issue are we ignoring here?

  4. +++ b/core/modules/jsonapi/tests/src/Functional/MediaTest.php
    @@ -342,7 +342,7 @@ protected function getExpectedUnauthorizedAccessCacheability() {
    -  // @codingStandardsIgnoreStart
    +  // phpcs:disable
    
    @@ -351,7 +351,7 @@ public function testPostIndividual() {
    -  // @codingStandardsIgnoreEnd
    +  // phpcs:enable
    

    I think this can just be removed?

  5. +++ b/core/tests/Drupal/KernelTests/Core/Theme/TwigMarkupInterfaceTest.php
    @@ -45,11 +45,11 @@ public function testMarkupInterfaceEmpty($expected, $variable) {
    -      // @codingStandardsIgnoreStart
    +      // phpcs:disable
           // The first argument to \Drupal\Core\StringTranslation\TranslatableMarkup
           // is not supposed to be an empty string.
           'empty TranslatableMarkup' => ['', new TranslatableMarkup('')],
    -      // @codingStandardsIgnoreEnd
    +      // phpcs:enable
    

    Maybe we can use // phpcs:ignore Drupal.Semantics.FunctionT.EmptyString here?

longwave’s picture

Also a wider question: in phpcs.xml.dist we ignore the Diff component:

  <!-- Exclude third-party code maintained within core that does not follow our standards. -->
  <!-- @todo This rule may be removed when https://www.drupal.org/node/1848264 is resolved. -->
  <exclude-pattern>./core/lib/Drupal/Component/Diff/</exclude-pattern>

Should we do this for the Doctrine tests instead of adding a line to each file?

(we could do the same for ProxyClass implementations, but I think as those can live in any namespace and are machine-generated it is worth explicitly including the tag)

quietone’s picture

Status: Needs work » Needs review
FileSize
3.46 KB
46.48 KB

Agree, let's fix these now. This patch address all the points in #8

quietone’s picture

#9. Now the change for doctrine. This removes ignoreFile lines from 29 files, if my count is correct leaving 45 files with phpcs:ignoreFile.

Spokje’s picture

Me like, just (at least for now) one nit:

only in patch2:
unchanged:
--- a/core/phpcs.xml.dist
+++ b/core/phpcs.xml.dist
@@ -14,6 +14,7 @@
   <!--Exclude folders used by common frontend tools. These folders match the file_scan_ignore_directories setting in default.settings.php-->
   <exclude-pattern>*/node_modules/*</exclude-pattern>
   <exclude-pattern>*/bower_components/*</exclude-pattern>
+  <exclude-pattern>./core/tests/Drupal/Tests/Component/Annotation/Doctrine/</exclude-pattern>
 
   <!--Exclude test files that are intentionally empty, or intentionally violate coding standards.-->
   <exclude-pattern>./modules/system/tests/fixtures/HtaccessTest</exclude-pattern>

Now it looks like Doctrine stuff is excluded because it's used by common frontend tools.

I think this added line deserves it's own comment to make clear why its excluded.

(Didn't want to interfere with the running tests and their status changing magic upon a failure, so left this issue on NR)

Spokje’s picture

Issue tags: +Coding standards
quietone’s picture

Adding a related issue I found but haven't yet read.

quietone’s picture

#12. Good point. This moves the line to 'exclude third party code' and adds a blank line for readability.

I read the related issue and it was to remove all the @codingstandardIgnoreFile lines and put exclusions in phpcs.xml. Not quite the same as what is being done here. We could expand the scope of this and add more exclusions, we have already added one. Or it could be a follow up to this. I can't decide which is better.

longwave mentioned the proxy class and tstoeckler commented about that in the related issue.

longwave’s picture

Status: Needs review » Needs work
+++ b/core/lib/Drupal/Core/TypedData/Validation/ExecutionContextFactory.php
@@ -43,6 +40,7 @@ public function __construct(TranslatorInterface $translator, $translationDomain
   public function createContext(ValidatorInterface $validator, $root)
+  // phpcs:ignore
   {

This was missed from #8.2, I think we just need to move the brace to the declaration line? Otherwise this looks good to me.

I didn't find the duplicate issue earlier, oops. I think this is hopefully less controversial. My personal opinion is that we should use the config file to exclude wide groups of files (e.g. entire namespaces) but then use inline comments for individual files that have individual reasons for being ignored.

quietone’s picture

Status: Needs work » Needs review
FileSize
710 bytes
46.55 KB
710 bytes

#16. Yes, I missed that. Oops.

Yes, let's save any controversy for another time.

longwave’s picture

Status: Needs review » Reviewed & tested by the community

Thanks, this looks good to me now.

I also opened #3208698: Make ProxyClass implementations follow coding standards as I think the best fix overall would be to make the ProxyClass implementations actually follow the standards, this should be possible with a little more effort in the generator code.

Spokje’s picture

Final nit/remark/suggestion:

Should we leave a comment in files NOT created by the generate-proxy-class script _why_ they are phpcs:ignoreFile?

Like for example:

--- a/core/lib/Drupal/Core/TypedData/Validation/ConstraintViolationBuilder.php
+++ b/core/lib/Drupal/Core/TypedData/Validation/ConstraintViolationBuilder.php
@@ -2,6 +2,8 @@
 
 namespace Drupal\Core\TypedData\Validation;
 
+// phpcs:ignoreFile
+// Ignored by PHPCS because large portions are a direct copy of 
+// vendor/symfony/validator/Violation/ConstraintViolationBuilder.php, which
+// uses a different code style from Drupal.
+
 use Drupal\Core\Validation\TranslatorInterface;
 use Symfony\Component\Validator\Constraint;
 use Symfony\Component\Validator\ConstraintViolation;

I had to search for a bit _why_ this file was ignored. Could save somebody some time someday.

Bows as he accepts the prize for the most usage of the word "some" in a sentence.

quietone’s picture

@Spokje, good idea. I am all for saving people work in the future. I think it would be OK to do that in #2891586: Remove @codingStandardsIgnoreFile from file and ignore those in phpcs.xml.dist because whether the phpcs:ignoreline are removed or become exclude lines in the phpcs.xml file or not, the changes should be documented. For me, it makes sense to do all that research in one issue.

Spokje’s picture

@quietone: Fine by me, let's leave this at RTBC

quietone’s picture

There is a duplicate of this issue #2891586: Remove @codingStandardsIgnoreFile from file and ignore those in phpcs.xml.dist with a similar patch. I suggest credit be added for jibran, tstoeckler, and xjm.

Spokje’s picture

@quietone:

In #19 I suggested adding comments to each phpcs:ignoreFile with an explanation why it's excluded.

In #20 you replied:

@Spokje, good idea. I am all for saving people work in the future. I think it would be OK to do that in #2891586: Remove @codingStandardsIgnoreFile from file and ignore those in phpcs.xml.dist

Since we (or rather you) closed #2891586: Remove @codingStandardsIgnoreFile from file and ignore those in phpcs.xml.dist as a duplicate, that commenting won't be happening there.
Do we want to do the commenting in this issue? Or a follow-up?

quietone’s picture

@Spokje, thanks! I completely forgot about that.

Spokje and I had a chat about this and after a bit of going in circles on my part I agree that documentation should be added here while we are modifying these files. It will save effort in the future. Thanks to Spokje for stopping my spin :-).

So, I went through patch and added comments where there it isn't obvious why the file is excluded. the comment is similar to #9, I went with namespace instead of filename as per DocParser.php. I also made the comment much shorter and started it on the same line as the ignoreFile. The idea was to reduce the visual impact since most people want to read the 'read' comments or the code.

Oh, core/tests/Drupal/FunctionalTests/AssertLegacyTrait.php doesn't need the ignoreFile any more either.

longwave’s picture

Status: Needs review » Reviewed & tested by the community

Great work, I agree with all the additions in #24 so back to RTBC.

Status: Reviewed & tested by the community » Needs work

The last submitted patch, 24: 3207968-24.patch, failed testing. View results

longwave’s picture

Status: Needs work » Reviewed & tested by the community

Random fail in EntityReferenceWidgetTest.

Spokje’s picture

Status: Reviewed & tested by the community » Needs work

The last submitted patch, 24: 3207968-24.patch, failed testing. View results

Spokje’s picture

Status: Needs work » Needs review
longwave’s picture

Status: Needs review » Reviewed & tested by the community
Spokje’s picture

*tips hat @longwave*

Version: 9.2.x-dev » 9.3.x-dev

Drupal 9.2.0-alpha1 will be released the week of May 3, 2021, which means new developments and disruptive changes should now be targeted for the 9.3.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Status: Reviewed & tested by the community » Needs work

The last submitted patch, 24: 3207968-24.patch, failed testing. View results

catch’s picture

Status: Needs work » Reviewed & tested by the community

Restoring status after HEAD was broken.

Status: Reviewed & tested by the community » Needs work

The last submitted patch, 24: 3207968-24.patch, failed testing. View results

Spokje’s picture

Status: Needs work » Reviewed & tested by the community

  • catch committed 6802ea3 on 9.3.x
    Issue #3207968 by quietone, longwave, Spokje: Replace @codingStandards...

  • catch committed 9f79130 on 9.2.x
    Issue #3207968 by quietone, longwave, Spokje: Replace @codingStandards...
catch’s picture

Version: 9.3.x-dev » 9.2.x-dev
Status: Reviewed & tested by the community » Fixed

Committed/pushed to 9.3.x and cherry-picked to 9.2.x, thanks!

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.