search

PHPCSStandards / PHP_CodeSniffer

PHP_CodeSniffer tokenizes PHP files and detects violations of a defined set of coding standards.
BSD 3-Clause "New" or "Revised" License
948 stars 57 forks source link

Document all the sniffs #434

Closed ghost closed 7 months ago

ghost commented 7 months ago

Is your feature request related to a problem?

There is no documentation for the sniffs. We can only reason about a sniff from a class name. Neither Wiki pages represents the destiny of the sniffs nor Sniff interface has a method like getDescription() or getDefinition() with code samples before/after.

Describe the solution you'd like

Add new method to the interface or maintain the Wiki.

Additional context (optional)

jrfnl commented 7 months ago

@javaDeveloperKid No clue what you are trying to suggest here, but your basic premise seems ill-informed.

The vast majority of PHPCS native sniffs have documentation and you can access the docs applicable to any standard via phpcs --generator=Text --standard=....

There's a discussion going in #317 to see about also making this information accessible via a web interface or via the wiki.

ghost commented 7 months ago

Thank you. However there is no way to know that if somebody didn't tell you this. No Wiki information and phpcs --help is not friendly as well. This tool should be more friendly for newcomers. I started using PHP CS Fixer when I was a junior developer and it was so easy. Now I'm senior and I've recently started using PHP Code Sniffer and it's not easy (I understand this might be a subjective opinion but still...).

jrfnl commented 7 months ago

@javaDeveloperKid I suggest you have a good read through the wiki and the help. All this info is available, though could possibly be better organized.

I understand you are running into the differences between CS Fixer and PHPCS, but that doesn't mean that PHPCS should become CS Fixer. These tools have significant differences, both in technology as well as in philosophy and that's not going to change.

I started using PHP CS Fixer when I was a junior developer and it was so easy. Now I'm senior and I've recently started using PHP Code Sniffer and it's not easy

There are plenty of people for whom the opposite is true (confusion when going from PHPCS to CS-fixer), so put your preconceptions aside and give the tool a chance based on its own merits

ghost commented 7 months ago

I will close this one for now as #317 is what I need. Thank you anyway, but please keep in mind the DX when maintaining this tool, escpecially when this is a tool that one has to, not wants to learn i.e. this is this kind of a tool that a developer wants to make work ASAP, because there is no value for developer to understand this tool. Very good DX should be no. 1 priority here.

Best regards

jrfnl commented 6 months ago

FYI: While it doesn't directly address this issue, PR #447 is a proposal to improve the help screens, including improved information on the help screen about finding documentation/rules for your ruleset.

Reviews and testing of that PR would be appreciated.