Establish a pattern of providing a link to explain a lint failure.

[andrewhowdencom]

This is essentially a copy paste from squizlabs/PHP_CodeSniffer#1603, but there's no core support yet.

Invariably, lints are used to communicate some piece of knowledge from one developer to another. However, a lint is not a good medium to communicate the nuance of a piece of knowledge (for example, "Try not to use unserialize"). Instead, projects like shellcheck provide a key that can be looked up in a wiki that explains the lint, as well as why it exists and another way to solve the issue the lint violates.

Example: https://github.com/koalaman/shellcheck/wiki/SC1003

Particularly within the Magento community it's been unclear what a lint is supposed to protect, as well as what we're supposed to do to get around it. Enforcing the requirement for such documentation would allow us to be much more transparent about our standards, and prevent large arbitrary decisions by people.

It would be good to establish such a pattern here. There are already keys that are provided (something like PSR2.Whitespace.Foo.Bar), which can be used as wiki pages. So, this request would consist of simply establishing a wiki that contained the necessary justification.

The GitHub wiki is a good place to host such knowledge, as in addition to the standards here, there are other project specific standards -- most of which seem to be in some way related to GitHub.

GitHub provides a URL shortener which can be used to add small strings at https://git.io/; for example:

https://git.io/vpo2C

GitHub pages would be another way of doing this, and can be fronted by a short domain (something like sniffs.extdn.org/r/You.Should.Not.Do.This/

[schmengler]

Thanks for bringing this up! Actually, our plan is to provide documentation of all rules with explanation why they are considered good practice. If there is a way to bake it into the code sniffer standard itself, great! Using the wiki seems like a good low-effort solution. We will consider that

[schmengler]

For now, each sniff will be accomplished by a markdown file with the same name in the same directory (FooSniff.md for FooSniff.php)

When including rules from other rulesets (MEQP2), a documentation is also added for those, mirroring the original directory structure.

[schmengler]

When including rules from other rulesets (MEQP2), a documentation is also added for those, mirroring the original directory structure.

Here's a first example: https://github.com/extdn/extdn-phpcs/pull/40/files