Selectively disable rules with codingStandardsIgnoreStart and codingStandardsIgnoreLine #604

westonruter · 2015-05-28T16:11:46Z

PHPCS supports comment directives like:

// @codingStandardsIgnoreFile
// @codingStandardsIgnoreStart
// @codingStandardsIgnoreLine

However, these are all or nothing. What would be even more useful is if we can selectively ignore certain sniffs or errors within sniffs. For instance:

$q = new WP_Query( array(
    'posts_per_page' => 200, // @codingStandardsIgnoreLine WordPress.VIP.SlowDBQuery.slow_db_query 
) );

or

// @codingStandardsIgnoreStart WordPress.VIP.SlowDBQuery.slow_db_query
$q = new WP_Query( array(
    'posts_per_page' => 200,
) );
// @codingStandardsIgnoreEnd WordPress.VIP.SlowDBQuery.slow_db_query

This draws inspiration from JSCS and its directives like:

//jscs:disable requireCamelCaseOrUpperCaseIdentifiers

We have this in the WordPress-Coding-Standards project in a sniff-specific ad hoc system of end-of-statement comments:

echo $foo; // xss ok

Which suppresses the WordPress.XSS.EscapeOutput sniff. But it would be very useful if this was standardized in PHPCS itself and available to all sniffs

The text was updated successfully, but these errors were encountered:

JDGrimes · 2015-05-28T16:16:09Z

👍

GaryJones · 2015-05-29T00:40:55Z

What format would the ignoring of multiple disabled rules take? Comma-separation?

westonruter · 2015-05-29T02:24:44Z

Comma-separated rules is what JSCS uses: http://jscs.info/overview.html#disabling-specific-rules

// jscs:disable requireCurlyBraces, requireDotNotation

jjeaton · 2015-09-09T19:00:32Z

👍

thiemowmde · 2015-12-16T12:14:19Z

👍

DanielSiepmann · 2015-12-17T14:47:55Z

👍

michaelhogg · 2015-12-23T13:59:02Z

👍

pdelre · 2016-04-01T14:29:01Z

👍

andrewhowdencom · 2016-05-10T01:50:40Z

scss-lint disables lint on a given "scope". See: https://github.com/brigade/scss-lint#disabling-linters-via-source

// scss-lint:disable ExampleSniff

eslint appears to work in a similar way. See: http://eslint.org/docs/user-guide/configuring.html#disabling-rules-with-inline-comments

/* eslint-disable no-alert */

In both cases it's useful to disable select lints for a given file, particularly as you're introducing new requirements over time (such as making code style stricter).

gsherwood · 2016-10-31T04:28:45Z

Related PEAR request: http://pear.php.net/bugs/bug.php?id=18885

Magnum5234 · 2017-07-07T06:43:51Z

👍

mikaelz · 2017-07-25T06:39:31Z

👍

Only one function, and three methods, were found to be violating the preferred WPCS naming conventions, so these lines have been excluded. While it does mean that the rest of the function signature line is also excluded from other checks, this seems like less of an issue than excluded the whole check from the rest of the project, which may allow other incorrectly named functions and methods to be accidentally introduced. Once squizlabs/PHP_CodeSniffer#604 is addressed, this ignores should be able to target just the specific check of the function / method name.

KacerCZ · 2017-10-21T04:49:29Z

Slevomat Coding standard has implemented something similar in its sniffs.
https://github.com/slevomat/coding-standard#suppressing-sniffs-locally

gsherwood · 2017-10-30T03:39:26Z

The prep for this change has been pushed: 5325170

I've added a new shorter comment syntax and put a bit more core support in. The syntax for disabling PHPCS and ignoring lines is now phpcs:disable and phpcs:ignore.

The next step is to get these comments to allow a list of sniff codes after them so they can selectively disable or ignore some errors.

If that's working, a possible extension would be to allow the new phpcs:enable syntax to re-enable selected sniff codes only, and the new phpcs:ignoreFile syntax to set ignore rules for a whole file, but I'm not sure how useful those features are and if I'll have time to do them.

glen-84 · 2017-10-30T07:08:33Z

@gsherwood Will we be able to put explanation text at the end of the line?

// phpcs:disable WordPress.VIP.SlowDBQuery.slow_db_query -- Because reason

gsherwood · 2017-10-30T21:36:31Z

Will we be able to put explanation text at the end of the line?

That's not something I had considered yet, but it's a good idea. It would need some sort of separator like you've put in your comment. Have you seen that syntax used elsewhere? Anyone else have any suggestions?

JDGrimes · 2017-10-30T21:43:33Z

Have you seen that syntax used elsewhere? Anyone else have any suggestions?

-- is one syntax for MySQL comments, and I think that it makes sense here. Can't think of anything better off of the top of my head.

…e specific sniffs (request #604)

gsherwood · 2017-10-31T04:42:10Z

While thinking about adding selective support for phpcs:ignoreFile I realised this isn't needed. The phpcs:ignoreFile comment tells PHPCS to quickly ignore the entire file from all checking. If you want to selectively disable rules for an entire file, you would use phpcs:disable sniff,sniff instead.

So I think the last feature to add is the ability to add your own comments.

glen-84 · 2017-10-31T07:29:02Z

It would need some sort of separator like you've put in your comment.

What if you matched one or more spaces followed by any non-word character?

Something like this: https://regex101.com/r/w1hwws/1

(could be improved a bit, but you get the idea)

Have you seen that syntax used elsewhere?

Not really, I just use it in my own projects/at work.

gsherwood · 2017-10-31T21:10:47Z

What if you matched one or more spaces followed by any non-word character?

That should be possible given the data that goes into those comments, but I'd prefer to decide on a specific syntax because it makes it easier to document and test.

mansona · 2017-10-31T21:27:59Z

Hey folks, I just wanted to weigh in here on the syntax of the comments. I would really recommend that you follow the syntax for eslint because it would allow for some good overlaps.

https://eslint.org/docs/user-guide/configuring#disabling-rules-with-inline-comments

as for the separators for "following comments", I would recommend something very simple. How about you just consider it as a list of comma separated rules which makes this valid

// eslint-disable-next-line no-console, this is more of a comment
console.log('face');

and becausethis is more of a comment doesn't match with any rule it just doesn't do anything.

Just an idea

Frenzie · 2017-10-31T22:00:35Z

@mansona
Wouldn't you expect it to spit out some kind of warning like "unrecognized rule" in that case?

-- is also how you add comments in Lua btw. I like the // phpcs:disable WordPress.VIP.SlowDBQuery.slow_db_query -- Because reason idea.

gsherwood · 2017-10-31T22:05:43Z

How about you just consider it as a list of comma separated rules which makes this valid

The new comment syntax does use a comma separated list of rules, but PHPCS doesn't know if they are valid or not because it doesn't only have a built-in list of sniffs. Plus, it allows for single words to mean something important (disable or enable an entire standard - see comment above #604 (comment)) and it supports setting sniff config vars (phpcs:set sniff var value).

I'd like a comment syntax that supports all those formats without confusion.

I could just assume they are sniff codes and throw them into the main array. But that means having to put a comma before your comment, like this:

phpcs:disable sniffCode, because reasons

And it makes life really hard if you want to comment a "disable all" style comment, like this:

phpcs:disable Because reasons

(is Because reasons a sniff code, or should it have been phpcs:disable , Because reasons?)

I think a separator is the way to go, and I think -- is probably a good one. That's going to be an easy change, so I'll implement -- and can change it later if a better idea pops up.

…ref #604)

gsherwood · 2017-10-31T22:26:35Z

I've added support for additional developer comments using the -- separator.

So you can now do this:

// phpcs:disable -- Turn off PHPCS
// phpcs:disable Generic.Commenting.Todo, PSR1.Files.SideEffects -- Because reasons

etc

You can also use block comments if you want something with more explanation. In this case, you don't need to use the comment separator because the explanation is on a different line:

/*
    We pasted this code in from a library doc and it needs to
    remain as is, so disable PHPCS for this block of code.
    phpcs:disable
*/

function Foo() {}

// phpcs:enable

mansona · 2017-10-31T22:26:45Z

@Frenzie I wouldn't expect an error in this case no, this process is about turning off errors so I don't think it would be necessary.

One thing I would like to add to the wider conversation here, I use these eslint style "overrides" every day, and have been for a few years now but never have I wanted to add "extra comments" to the one line

I don't see anything wrong with the following if you really need that:

// allow for console.log here so that we can tell the user something
// eslint-disable-next-line no-console
console.log('face');

I'd much rather a simple case like this ☝️ than over-complicate the syntax.

gsherwood · 2017-10-31T22:28:40Z

I don't see anything wrong with the following if you really need that:

// allow for console.log here so that we can tell the user something
// eslint-disable-next-line no-console
console.log('face');
I'd much rather a simple case like this ☝️ than over-complicate the syntax.

You can do that with the new PHPCS syntax as well. The benefit of putting it all on one line (if it is a short message) is that the comment line itself is completely ignored by PHPCS and doesn't need to confirm to your standard's comment rules. That's not something I personally care about, but I think other developers do.

gsherwood · 2017-10-31T22:39:08Z

I'll throw this idea into feedback for a while, but I think this feature is now done.

@claudiosanches

Ignoring PHPCS in two lines of the code where apparently it is not possible to fix the violations. I tried using what @claudiosanches suggested in this comment #17909 (comment) but both tags didn't work. Lets revisit this when PHPCS 3.2.0 is released and we can selectively disable rules (see squizlabs/PHP_CodeSniffer#604).

o5 · 2017-12-14T19:11:54Z

I'm using sniff Generic.Files.LineLength. I would like to disable it for specific line. It works when I place this comment above of long line. But it does not work on same line:

[
    'foo' => 'very_long_string...' , // phpcs:disable Generic.Files.LineLength.TooLong
]

In case of $lineLimit is 30 warning occurs:

FOUND 0 ERRORS AND 1 WARNING AFFECTING 1 LINE
----------------------------------------------------------------------
 2 | WARNING | Line exceeds 30 characters; contains 87 characters
   |         | (Generic.Files.LineLength.TooLong)

gsherwood · 2017-12-14T21:40:11Z

@o5 The // phpcs:disable syntax disable that error message from that comment onwards. If you want to ignore that line, you need to use // phpcs:ignore. Some docs here: https://github.com/squizlabs/PHP_CodeSniffer/wiki/Advanced-Usage#ignoring-parts-of-a-file

Edit: I'd also suggest ignoring the whole sniff given that the really long comment is probably going to push the line length to MaxExceeded. So I'd suggest // phpcs:ignore Generic.File.LineLength

o5 · 2018-02-08T17:09:26Z

@gsherwood Option $ignoreComments=true for Generic.Files.LineLength resolves my issue :)

ahmadawais · 2018-07-16T14:04:50Z

This issue shows up a lot in the search so I just wanted to share this as a result of this discussion.

The @codingStandards syntax is deprecated as of v3.2.0, use phpcs instead.

Some examples:

For Multi-line disable

// phpcs:disable
// phpcs:enable

For Single line ignore

// phpcs:ignore

See this page for more information: https://github.com/squizlabs/PHP_CodeSniffer/wiki/Advanced-Usage#ignoring-parts-of-a-file

Peace! ✌️

flobee · 2018-09-24T16:38:48Z

Gooood feature!
One hint: Hints for the editors needed to search and select for eg: @phpcs<strg+space> :) like it works in phpunit apigen Codeception ... and others. Or does it exists and i dont know how?

I prefer using @ annotations which works like:

/**
 * ....
 * @phpcs:ignoreFile

BenBroide · 2020-03-31T19:13:00Z

For disabling and enabling a specific rule

// phpcs:disable WordPress.PHP.DevelopmentFunctions
error_log( $error_message );
// phpcs:enable WordPress.PHP.DevelopmentFunctions

Only one function, and three methods, were found to be violating the preferred WPCS naming conventions, so these lines have been excluded. While it does mean that the rest of the function signature line is also excluded from other checks, this seems like less of an issue than excluded the whole check from the rest of the project, which may allow other incorrectly named functions and methods to be accidentally introduced. Once squizlabs/PHP_CodeSniffer#604 is addressed, this ignores should be able to target just the specific check of the function / method name.

westonruter mentioned this issue May 28, 2015

Standardize whitelisting by using sniff name WordPress/WordPress-Coding-Standards#393

Closed

westonruter mentioned this issue Sep 9, 2015

Documentation for all the whitelist comments WordPress/WordPress-Coding-Standards#446

Closed

gsherwood mentioned this issue Jan 18, 2016

Create a new kind of annotation to ignore some specific rules inside a class, method, ... #866

Closed

gsherwood added the Type: enhancement label Jan 20, 2016

Progi1984 mentioned this issue May 18, 2016

Methods for StreamWrapper are declared in error #1003

Closed

gsherwood mentioned this issue Sep 28, 2016

Possible to make PHPCS ignore one given rule for a particular file? #1179

Closed

gsherwood mentioned this issue Nov 13, 2016

Add rule suppresion for a line or scope #1211

Closed

gsherwood added the High Priority label Apr 5, 2017

gsherwood added this to the 3.2.0 milestone Jul 7, 2017

widoz mentioned this issue Aug 28, 2017

Improve Wpcs churchthemes/widget-importer-exporter#20

Closed

GaryJones mentioned this issue Oct 5, 2017

CS: Unexclude ValidFunctionName checks wp-cli/wp-cli#4400

Merged

gsherwood added a commit that referenced this issue Oct 30, 2017

The phpcs:disable and phpcs:ignore comments can now selectively ignor…

1f07a69

…e specific sniffs (request #604)

This was referenced Oct 31, 2017

SideEffectsSniff does not obey localised ignore annotations #327

Closed

@codingStandardsIgnoreStart does not work #1258

Closed

This was referenced Oct 31, 2017

Drop PHPCS 2.x support by August 31, 2018 WordPress/WordPress-Coding-Standards#1048

Closed

WhiteSpace.PrecisionAlignment: Allow for the new PHPCS ignore comments WordPress/WordPress-Coding-Standards#1218

Closed

gsherwood added a commit that referenced this issue Oct 31, 2017

Added support for additional comments at the end of phpcs: comments (…

54627e0

…ref #604)

gsherwood added the Status: awaiting feedback label Oct 31, 2017

gsherwood removed the Status: awaiting feedback label Nov 22, 2017

gsherwood closed this as completed Nov 22, 2017

jrfnl mentioned this issue Nov 28, 2017

Multiline indented string concatenation WordPress/WordPress-Coding-Standards#1243

Closed

dependencies bot mentioned this issue Aug 7, 2018

Update squizlabs/php_codesniffer in composer.json from ^2.5.1 to 3.3.1 CNHCircleK/cnhcirclek.org#54

Closed

jrfnl mentioned this issue Aug 17, 2018

Prevent false positives by ignoring commented lines wpengine/phpcompat#195

Open

jrfnl mentioned this issue Dec 20, 2018

Deprecate use of the WPCS native whitelist comments WordPress/WordPress-Coding-Standards#1580

Merged

2 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Selectively disable rules with codingStandardsIgnoreStart and codingStandardsIgnoreLine #604

Selectively disable rules with codingStandardsIgnoreStart and codingStandardsIgnoreLine #604

westonruter commented May 28, 2015

JDGrimes commented May 28, 2015

GaryJones commented May 29, 2015

westonruter commented May 29, 2015

jjeaton commented Sep 9, 2015

thiemowmde commented Dec 16, 2015

DanielSiepmann commented Dec 17, 2015

michaelhogg commented Dec 23, 2015

pdelre commented Apr 1, 2016

andrewhowdencom commented May 10, 2016 •

edited

Loading

gsherwood commented Oct 31, 2016

Magnum5234 commented Jul 7, 2017

mikaelz commented Jul 25, 2017

KacerCZ commented Oct 21, 2017

gsherwood commented Oct 30, 2017

glen-84 commented Oct 30, 2017

gsherwood commented Oct 30, 2017

JDGrimes commented Oct 30, 2017

gsherwood commented Oct 31, 2017

glen-84 commented Oct 31, 2017

gsherwood commented Oct 31, 2017

mansona commented Oct 31, 2017

Frenzie commented Oct 31, 2017 •

edited

Loading

gsherwood commented Oct 31, 2017

gsherwood commented Oct 31, 2017

mansona commented Oct 31, 2017

gsherwood commented Oct 31, 2017

gsherwood commented Oct 31, 2017 •

edited

Loading

o5 commented Dec 14, 2017 •

edited

Loading

gsherwood commented Dec 14, 2017 •

edited

Loading

o5 commented Feb 8, 2018

ahmadawais commented Jul 16, 2018 •

edited

Loading

flobee commented Sep 24, 2018

BenBroide commented Mar 31, 2020

Selectively disable rules with codingStandardsIgnoreStart and codingStandardsIgnoreLine #604

Selectively disable rules with codingStandardsIgnoreStart and codingStandardsIgnoreLine #604

Comments

westonruter commented May 28, 2015

JDGrimes commented May 28, 2015

GaryJones commented May 29, 2015

westonruter commented May 29, 2015

jjeaton commented Sep 9, 2015

thiemowmde commented Dec 16, 2015

DanielSiepmann commented Dec 17, 2015

michaelhogg commented Dec 23, 2015

pdelre commented Apr 1, 2016

andrewhowdencom commented May 10, 2016 • edited Loading

gsherwood commented Oct 31, 2016

Magnum5234 commented Jul 7, 2017

mikaelz commented Jul 25, 2017

KacerCZ commented Oct 21, 2017

gsherwood commented Oct 30, 2017

glen-84 commented Oct 30, 2017

gsherwood commented Oct 30, 2017

JDGrimes commented Oct 30, 2017

gsherwood commented Oct 31, 2017

glen-84 commented Oct 31, 2017

gsherwood commented Oct 31, 2017

mansona commented Oct 31, 2017

Frenzie commented Oct 31, 2017 • edited Loading

gsherwood commented Oct 31, 2017

gsherwood commented Oct 31, 2017

mansona commented Oct 31, 2017

gsherwood commented Oct 31, 2017

gsherwood commented Oct 31, 2017 • edited Loading

o5 commented Dec 14, 2017 • edited Loading

gsherwood commented Dec 14, 2017 • edited Loading

o5 commented Feb 8, 2018

ahmadawais commented Jul 16, 2018 • edited Loading

For Multi-line disable

For Single line ignore

flobee commented Sep 24, 2018

BenBroide commented Mar 31, 2020

andrewhowdencom commented May 10, 2016 •

edited

Loading

Frenzie commented Oct 31, 2017 •

edited

Loading

gsherwood commented Oct 31, 2017 •

edited

Loading

o5 commented Dec 14, 2017 •

edited

Loading

gsherwood commented Dec 14, 2017 •

edited

Loading

ahmadawais commented Jul 16, 2018 •

edited

Loading