magento / magento/magento-coding-standard
Document all existing rules
- Dominant language
- PHP
- Stars
- 375
- Forks
- 165
- PR merge metrics
- No merged PRs in 30d
Description
### Description
As a developer I develop some code and running magento coding standard static tests against my code. But it's not clear what to do in case of some issue.
Example:
```
PHP Code Sniffer detected 2 violation(s):
FILE: .../app/code/Magento/Checkout/Model/TotalsInformationManagement.php
----------------------------------------------------------------------
FOUND 4 ERRORS AFFECTING 4 LINES
----------------------------------------------------------------------
41 | ERROR | [x] If the @inheritdoc not inline it shouldn’t have
| | braces
43 | ERROR | [x] {@inheritdoc} does not import parameter annotation
65 | ERROR | [x] Missing short description
66 | ERROR | [x] There must be exactly one blank line before tags
----------------------------------------------------------------------
PHPCBF CAN FIX THE 4 MARKED SNIFF VIOLATIONS AUTOMATICALLY
----------------------------------------------------------------------
Failed asserting that 2 matches expected 0.
```
Let's imaging I'm just first time created some PR to magento2 and got these issues, I don't really know **what to do with following things**:
- If the @inheritdoc not inline it shouldn’t have braces
- {@inheritdoc} does not import parameter annotation
- Missing short description
I didn't even knew how to run these static tests, as they were ran on some Magento infra and shown me just result (commands that I could run is not shown anywhere) --> I don't know how to run this phpcbf.
So I'm trying to google these things, but just googling of these reports isn't getting any valid result:
https://www.google.com/search?q=If+the+%40inheritdoc+not+inline+it+shouldn%27t+have+braces+magento2
https://www.google.com/search?q=%7B%40inheritdoc%7D+does+not+import+parameter+annotation+magento2
https://www.google.com/search?q=Missing+short+description+magento2
Only one "There must be exactly one blank line before tags" is quite clear.
This is just example of things that quite obvious.
Let's imaging that should I do in case if i'll get following message: `The use of function pathinfo() is discouraged` and I didn't even touched the place that was using this function (related to https://github.com/magento/magento-coding-standard/issues/102).
It will be absolutely not clear.
### Proposal
- Document all existing rules and what messages are they reporting.
- Add info WHY it was created, what should be used instead, exceptions (example https://github.com/magento/magento2/pull/25133#issuecomment-544493482) and **how to ignore this rule** (in case if you didn't touched that place and don't want to brake anything)
Contributor guide
Research direction
Start by inventorying the existing Magento coding-standard rules behind the reported PHPCS and PHPCBF messages, including the examples in this issue and related issue #102. Document each rule's message, rationale, alternatives, exceptions, invocation commands, and ignore guidance, using the referenced Magento pull request comment for context; done means all existing rules are covered.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- php
- Domain
- developer-experience, documentation, tooling
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100