Skip to content

Commit 2b6e5f1

Browse files
author
Vincent Langlet
committed
📚 Improve docs
1 parent 31e702c commit 2b6e5f1

File tree

3 files changed

+243
-45
lines changed

3 files changed

+243
-45
lines changed

‎README.md

Lines changed: 4 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,47 +1,6 @@
11
# Symfony3 Custom PHP CodeSniffer Coding Standard
22

3-
This standard can be installed with the [Composer](https://getcomposer.org/) dependency manager.
4-
5-
1. Add the repository to your composer.json:
6-
7-
```json
8-
"repositories": [
9-
{
10-
"type": "vcs",
11-
"url": "git@github.com:VincentLanglet/Symfony3-custom-coding-standard"
12-
}
13-
]
14-
```
15-
16-
2. Add the coding standard as a dependency of your project
17-
18-
```json
19-
"require-dev": {
20-
"vincentlanglet/symfony3-custom-coding-standard": "^2.18"
21-
},
22-
```
23-
24-
3. Add the coding standard to the PHP_CodeSniffer install path
25-
26-
The path is relative to the php_codesniffer install path. This is important to make it work both in your vagrant, local machine and PHPStorm
27-
28-
```
29-
bin/phpcs --config-set installed_paths ../../vincentlanglet/symfony3-custom-coding-standard
30-
```
31-
32-
4. Check the installed coding standards
33-
34-
```
35-
bin/phpcs -i
36-
```
37-
38-
5. Done!
39-
40-
```
41-
bin/phpcs --standard=Symfony3Custom /path/to/code
42-
```
43-
44-
6. (optional) Set up PHPStorm
45-
46-
- configure code sniffer under Languages & Frameworks -> PHP -> Code Sniffer
47-
- Go to Editor -> Inspections -> PHP Code sniffer, refresh the standards and select Symfony3Custom
3+
Documentation
4+
-------------
5+
* [Coding Standard](docs/coding-standard.md)
6+
* [Installation](docs/installation.md)

‎docs/coding-standard.md

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
# Coding Standard Rules
2+
## General
3+
We added
4+
- `PSR1` and `PSR2` rules
5+
6+
- All `Zend` rules except:
7+
8+
```
9+
<rule ref="Zend.NamingConventions.ValidVariableName.PrivateNoUnderscore">
10+
<severity>0</severity>
11+
</rule>
12+
13+
<rule ref="Zend.NamingConventions.ValidVariableName.ContainsNumbers">
14+
<severity>0</severity>
15+
</rule>
16+
```
17+
18+
## From symfony
19+
From [symfony standard](http://symfony.com/doc/current/contributing/code/standards.html)
20+
21+
### Structure
22+
- Add a single space after each comma delimiter
23+
24+
```
25+
<rule ref="Symfony3Custom.WhiteSpace.CommaSpacing" />
26+
```
27+
28+
- Add a single space around binary operators (`==`, `&&`, `...`)
29+
30+
```
31+
<rule ref="Symfony3Custom.WhiteSpace.BinaryOperatorSpacing" />
32+
```
33+
34+
We do not respect the exception of the concatenation (`.`) operator
35+
```
36+
<rule ref="Squiz.Strings.ConcatenationSpacing">
37+
<properties>
38+
<property name="spacing" value="1"/>
39+
<property name="ignoreNewlines" value="true" />
40+
</properties>
41+
</rule>
42+
```
43+
44+
- Place unary operators (`!`, `--`, `...`) adjacent to the affected variable
45+
46+
```
47+
<rule ref="Symfony3Custom.WhiteSpace.SpaceUnaryOperatorSpacing" />
48+
```
49+
50+
- Add a comma after each array item in a multi-line array, even after the last one
51+
52+
```
53+
<rule ref="Symfony3Custom.Array.MultiLineArrayComma" />
54+
```
55+
56+
- Add a blank line before return statements,
57+
unless the return is alone inside a statement-group (like an `if` statement)
58+
59+
```
60+
<rule ref="Symfony3Custom.Formatting.BlankLineBeforeReturn" />
61+
```
62+
63+
- Use `return null` when a function explicitly returns null values
64+
and use `return` when the function returns void values
65+
66+
```
67+
<rule ref="Symfony3Custom.Commenting.FunctionComment" />
68+
```
69+
70+
- Use braces to indicate control structure body regardless of the number of statements it contains
71+
72+
Covered by `PSR2`
73+
74+
- Define one class per file
75+
76+
```
77+
<rule ref="Symfony3Custom.Classes.MultipleClassesOneFile" />
78+
```
79+
80+
- Declare the class inheritance and all the implemented interfaces on the same line as the class name
81+
82+
Covered by `PSR2`
83+
84+
- Declare class properties before methods
85+
86+
```
87+
<rule ref="Symfony3Custom.Classes.PropertyDeclaration" />
88+
```
89+
90+
- Declare public methods first, then protected ones and finally private ones.
91+
The exceptions to this rule are the class constructor and the `setUp()` and `tearDown()` methods of PHPUnit tests,
92+
which must always be the first methods to increase readability
93+
94+
```
95+
<rule ref="Symfony3Custom.Functions.ScopeOrder" />
96+
```
97+
98+
- Declare all the arguments on the same line as the method/function name,
99+
no matter how many arguments there are
100+
101+
Not checked because of the limit of 120 characters per line
102+
103+
- Use parentheses when instantiating classes regardless of the number of arguments the constructor has
104+
105+
```
106+
<rule ref="Symfony3Custom.Objects.ObjectInstantiation" />
107+
```
108+
109+
- Do not use spaces around `[` offset accessor and before `]` offset accessor
110+
111+
```
112+
<rule ref="Squiz.Arrays.ArrayBracketSpacing"/>
113+
```
114+
115+
### Naming Conventions
116+
117+
- Use camelCase, not underscores, for variable, function and method names, arguments
118+
119+
Covered by `PSR2` and `Zend`
120+
121+
- Use namespaces for all classes
122+
123+
Covered by `PSR1`
124+
```
125+
<rule ref="Squiz.Classes.ValidClassName" />
126+
```
127+
128+
- Prefix abstract classes with `Abstract`
129+
130+
```
131+
<rule ref="Symfony3Custom.NamingConventions.ValidClassName" />
132+
```
133+
134+
- Suffix interfaces with `Interface`
135+
136+
```
137+
<rule ref="Symfony3Custom.NamingConventions.ValidClassName" />
138+
```
139+
140+
- Suffix traits with `Trait`
141+
142+
```
143+
<rule ref="Symfony3Custom.NamingConventions.ValidClassName" />
144+
```
145+
146+
- Suffix exceptions with `Exception`
147+
148+
```
149+
<rule ref="Symfony3Custom.NamingConventions.ValidClassName" />
150+
```
151+
152+
- For type-hinting in PHPDocs and casting, use `bool`, `int` and `float`
153+
154+
```
155+
<rule ref="Symfony3Custom.NamingConventions.ValidScalarTypeName" />
156+
```
157+
158+
### Documentation
159+
160+
- Add PHPDoc blocks for all classes, methods, and functions
161+
162+
We added exceptions for functions `setUp`, `tearDown` and `tests` with no `@param` or `@return`
163+
```
164+
<rule ref="Symfony3Custom.Commenting.ClassComment" />
165+
<rule ref="Symfony3Custom.Commenting.FunctionComment" />
166+
```
167+
168+
We added exceptions for param comments
169+
```
170+
<rule ref="Symfony3Custom.Commenting.FunctionComment.MissingParamComment">
171+
<severity>0</severity>
172+
</rule>
173+
```
174+
175+
- Group annotations together so that annotations of the same type immediately follow each other,
176+
and annotations of a different type are separated by a single blank line
177+
178+
```
179+
<rule ref="Symfony3Custom.Commenting.DocCommentGroupSameType" />
180+
```
181+
182+
- Omit the `@return` tag if the method does not return anything
183+
184+
```
185+
<rule ref="Symfony3Custom.Commenting.FunctionComment" />
186+
```
187+
188+
- The `@package` and `@subpackage` annotations are not used
189+
190+
```
191+
<rule ref="Symfony3Custom.Commenting.DocCommentForbiddenTags" />
192+
```

‎docs/installation.md

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Installation
2+
3+
This standard can be installed with the [Composer](https://getcomposer.org/) dependency manager.
4+
5+
1. Add the repository to your composer.json:
6+
7+
```json
8+
"repositories": [
9+
{
10+
"type": "vcs",
11+
"url": "git@github.com:VincentLanglet/Symfony3-custom-coding-standard"
12+
}
13+
]
14+
```
15+
16+
2. Add the coding standard as a dependency of your project
17+
18+
```json
19+
"require-dev": {
20+
"vincentlanglet/symfony3-custom-coding-standard": "^2.18"
21+
},
22+
```
23+
24+
3. Add the coding standard to the PHP_CodeSniffer install path
25+
26+
The path is relative to the php_codesniffer install path. This is important to make it work both in your vagrant, local machine and PHPStorm
27+
28+
```
29+
bin/phpcs --config-set installed_paths ../../vincentlanglet/symfony3-custom-coding-standard
30+
```
31+
32+
4. Check the installed coding standards
33+
34+
```
35+
bin/phpcs -i
36+
```
37+
38+
5. Done!
39+
40+
```
41+
bin/phpcs --standard=Symfony3Custom /path/to/code
42+
```
43+
44+
6. (optional) Set up PHPStorm
45+
46+
- configure code sniffer under Languages & Frameworks -> PHP -> Code Sniffer
47+
- Go to Editor -> Inspections -> PHP Code sniffer, refresh the standards and select Symfony3Custom

0 commit comments

Comments
 (0)