magento / magento/magento-coding-standard

Document all existing rules

Open
#154 0 comments 2 reactions 0 assignees View on GitHub
enhancement Progress: ready for dev
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.