Skip to content

Commit 09c629f

Browse files
jrfnljrfnl
committed
WhiteSpace/ControlStructureSpacing: add documentation
Follow up on closed PR 1736, but now with correct descriptions and standard blocks and code samples for all things being flagged by the sniff. Related to 1722 Prop to ckanitz for the initial draft.
1 parent 2d7f396 commit 09c629f

File tree

1 file changed

+150
-0
lines changed

1 file changed

+150
-0
lines changed

‎WordPress/Docs/WhiteSpace/ControlStructureSpacingStandard.xml

+150
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
<?xml version="1.0"?>
2+
<documentation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
3+
xsi:noNamespaceSchemaLocation="https://phpcsstandards.github.io/PHPCSDevTools/phpcsdocs.xsd"
4+
title="Control Structure Spacing"
5+
>
6+
<standard>
7+
<![CDATA[
8+
Put one space on both sides of the opening and closing parentheses of control structures.
9+
]]>
10+
</standard>
11+
<code_comparison>
12+
<code title="Valid: One space on each side of the open and close parentheses.">
13+
<![CDATA[
14+
while<em> ( </em>have_posts()<em> ) </em>{}
15+
16+
// For multi-line conditions,
17+
// a new line is also accepted.
18+
if<em> ( </em>true === $condition
19+
&& $count > 10
20+
<em>) </em>{}
21+
]]>
22+
</code>
23+
<code title="Invalid: Incorrect spacing around the open and close parentheses.">
24+
<![CDATA[
25+
// No spaces.
26+
while<em>(</em>have_posts()<em>)</em>{}
27+
28+
// Too much space.
29+
while<em> ( </em>have_posts()<em> ) </em>{}
30+
]]>
31+
</code>
32+
</code_comparison>
33+
<standard>
34+
<![CDATA[
35+
The open brace for the control structure must be on the same line as the close parenthesis or the control structure keyword, with one space between them.
36+
]]>
37+
</standard>
38+
<code_comparison>
39+
<code title="Valid: Open brace on the same line as the keyword/close parenthesis.">
40+
<![CDATA[
41+
try<em> {</em>
42+
// Do something.
43+
} catch (
44+
ExceptionA | ExceptionB $e
45+
<em>) {</em>
46+
}
47+
]]>
48+
</code>
49+
<code title="Invalid: Open brace on a different line than the keyword/close parenthesis.">
50+
<![CDATA[
51+
try
52+
<em>{</em>
53+
// Do something.
54+
} catch ( Exception $e )
55+
<em>(</em>
56+
}
57+
]]>
58+
</code>
59+
</code_comparison>
60+
<code_comparison>
61+
<code title="Valid: One space between the keyword/close parenthesis and the open brace.">
62+
<![CDATA[
63+
if ( $condition )<em> </em>{
64+
// Do something.
65+
}
66+
]]>
67+
</code>
68+
<code title="Invalid: Too much space between the keyword/close parenthesis and the open brace.">
69+
<![CDATA[
70+
if ( $condition )<em> </em>{
71+
// Do something.
72+
}
73+
]]>
74+
</code>
75+
</code_comparison>
76+
<standard>
77+
<![CDATA[
78+
When using alternative control structure syntaxes, there should be one space between the close parenthesis and the colon opening the control structure body.
79+
]]>
80+
</standard>
81+
<code_comparison>
82+
<code title="Valid: One space before the colon.">
83+
<![CDATA[
84+
foreach ( $types as $type )<em> </em>:
85+
// Do something.
86+
endforeach;
87+
]]>
88+
</code>
89+
<code title="Invalid: No space before the colon.">
90+
<![CDATA[
91+
foreach ( $types as $type )<em></em>:
92+
// Do something.
93+
endforeach;
94+
]]>
95+
</code>
96+
</code_comparison>
97+
<standard>
98+
<![CDATA[
99+
When a control structure is nested in another control structure and the closing braces follow each other, there should be no blank line between the closing braces.
100+
]]>
101+
</standard>
102+
<code_comparison>
103+
<code title="Valid: No blank line between the consecutive close braces.">
104+
<![CDATA[
105+
if ( $a === $b ) {
106+
if ( $something ) {
107+
// Do something.
108+
}
109+
}
110+
]]>
111+
</code>
112+
<code title="Invalid: Blank line(s) between the consecutive close braces.">
113+
<![CDATA[
114+
if ( $a === $b ) {
115+
if ( $something ) {
116+
// Do something.
117+
}<em>
118+
119+
120+
</em>}
121+
]]>
122+
</code>
123+
</code_comparison>
124+
<standard>
125+
<![CDATA[
126+
[Optional, turned off by default]
127+
There should be no blank line(s) at the start or end of the control structure body.
128+
]]>
129+
</standard>
130+
<code_comparison>
131+
<code title="Valid: No blank lines at the start or end of the control structure body.">
132+
<![CDATA[
133+
if ( $a === $b ) {
134+
echo $a;
135+
}
136+
]]>
137+
</code>
138+
<code title="Invalid: Blank line(s) at the start and end of the control structure body.">
139+
<![CDATA[
140+
if ( $a === $b ) {
141+
<em>
142+
143+
</em> echo $a;
144+
<em>
145+
146+
</em>}
147+
]]>
148+
</code>
149+
</code_comparison>
150+
</documentation>

0 commit comments

Comments
 (0)