Fix 'Drupal.Commenting.FileComment' coding standard again

Follow-up to #2572643: Fix 'Drupal.Commenting.FileComment' coding standard, Part of #2571965: [meta] Fix PHP coding standards in core, stage 1.

Approach

We are testing coding standards with PHP CodeSniffer, using the Drupal coding standards from the Coder module. Both of these packages are not installed in Drupal core. We need to do a couple of steps in order to download and configure them so we can run a coding standards check.

Step 1: Remove the coding standard from the blacklist

Every coding standard is identified by a "sniff". For example, an imaginary coding standard that would require all llamas to be placed inside a square bracket fence would be called the "Drupal.AnimalControlStructure.BracketedFence sniff". There are dozens of such coding standards, and to make the work easier we have started by blacklisting all the sniffs. For the moment all coding standards that are not yet fixed are simply skipped during the test.

Open the file core/phpcs.xml.dist and remove the line that matches the sniff of this ticket (it's in the issue title). Make sure your patch will include the removal of this line.

Step 2: Install PHP CodeSniffer and the ruleset from the Coder module

Both of these packages are not installed by default in Drupal core, so we need to download them. This can be done with Composer, from the root folder of your Drupal installation:

$ composer require drupal/coder squizlabs/php_codesniffer

Step 3: Prepare the phpcs.xml file

Next we need to make a copy of the file phpcs.xml.dist (in the core/ folder) and save it as phpcs.xml. This is the configuration file for PHP CodeSniffer.

We have to configure the location of the Drupal coding standard ruleset from the Coder module that we just downloaded. To do this open the newly created file core/phpcs.xml. Find the line containing:

<rule ref="Drupal">

Change it to:

<rule ref="../vendor/drupal/coder/coder_sniffer/Drupal">

Or if you prefer the command line:

$ cd core/
$ cp phpcs.xml.dist phpcs.xml
$ perl -pi -e "s|ref=\"Drupal|ref=\"../vendor/drupal/coder/coder_sniffer/Drupal|" phpcs.xml

Step 4: Run the test

Now you are ready to run the test! From within the core/ folder, run the following command to launch the test:

$ ../vendor/bin/phpcs -p

This takes a couple of minutes. The -p flag shows the progress, so you have a bunch of nice dots to look at while it is running.

Step 5: Fix the failures

When the test is complete it will present you a list of all the files that contain violations of your sniff, and the line numbers where the violations occur. Go ahead and fix them all!