Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Documentation] PSR12 - Control Structure Spacing #182

Merged
merged 21 commits into from
Jan 26, 2024
Merged

[Documentation] PSR12 - Control Structure Spacing #182

Changes from 17 commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
5a0186f
Add the documentation for the PSR12 Control Structure Spacing sniff
dingo-d Dec 23, 2023
f4fabf1
Update src/Standards/PSR12/Docs/ControlStructures/ControlStructureSpa…
dingo-d Jan 17, 2024
62cd376
Update src/Standards/PSR12/Docs/ControlStructures/ControlStructureSpa…
dingo-d Jan 17, 2024
baf28e9
Update src/Standards/PSR12/Docs/ControlStructures/ControlStructureSpa…
dingo-d Jan 17, 2024
5961ed8
Update src/Standards/PSR12/Docs/ControlStructures/ControlStructureSpa…
dingo-d Jan 17, 2024
e2f79ab
Update src/Standards/PSR12/Docs/ControlStructures/ControlStructureSpa…
dingo-d Jan 17, 2024
4ac58b1
Update src/Standards/PSR12/Docs/ControlStructures/ControlStructureSpa…
dingo-d Jan 17, 2024
c14c5dd
Update src/Standards/PSR12/Docs/ControlStructures/ControlStructureSpa…
dingo-d Jan 17, 2024
8041c8b
Update src/Standards/PSR12/Docs/ControlStructures/ControlStructureSpa…
dingo-d Jan 17, 2024
a57752b
Update src/Standards/PSR12/Docs/ControlStructures/ControlStructureSpa…
dingo-d Jan 17, 2024
0b63cb0
Update src/Standards/PSR12/Docs/ControlStructures/ControlStructureSpa…
dingo-d Jan 17, 2024
1bf2c27
Update src/Standards/PSR12/Docs/ControlStructures/ControlStructureSpa…
dingo-d Jan 17, 2024
f6ec02b
Update src/Standards/PSR12/Docs/ControlStructures/ControlStructureSpa…
dingo-d Jan 17, 2024
383618b
Update src/Standards/PSR12/Docs/ControlStructures/ControlStructureSpa…
dingo-d Jan 17, 2024
cdeef4d
Update src/Standards/PSR12/Docs/ControlStructures/ControlStructureSpa…
dingo-d Jan 17, 2024
c62e10f
Update src/Standards/PSR12/Docs/ControlStructures/ControlStructureSpa…
dingo-d Jan 17, 2024
a1795c1
Improve readability of the documentation
dingo-d Jan 18, 2024
b38b4b7
Update src/Standards/PSR12/Docs/ControlStructures/ControlStructureSpa…
dingo-d Jan 22, 2024
f593a53
Fix suggestions from the PR
dingo-d Jan 25, 2024
6a22d05
Update the standard description for single line control structures
dingo-d Jan 26, 2024
77366bb
Update src/Standards/PSR12/Docs/ControlStructures/ControlStructureSpa…
dingo-d Jan 26, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
124 changes: 124 additions & 0 deletions src/Standards/PSR12/Docs/ControlStructures/ControlStructureSpacingStandard.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,124 @@
<documentation title="Control Structure Spacing">
<standard>
<![CDATA[
The control structures must have one space after the control structure keyword, no spaces after the opening parenthesis and before the closing parenthesis, and one space between the closing parenthesis and the opening brace.
]]>
</standard>
<code_comparison>
<code title="Valid: No space after the opening parenthesis in a single-line condition.">
<![CDATA[
if <em>(</em>$expr) {
}
]]>
</code>
<code title="Invalid: Space after the opening parenthesis in a single-line condition.">
<![CDATA[
if <em>( </em>$expr) {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should the "no space after the keyword" rule get its own code sample ? Or could this be included in this invalid code sample ?

Suggested change
if <em>( </em>$expr) {
if<em> ( </em>$expr) {

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Technically, this sniff doesn't check for the space after the keyword. This is covered by the Squiz.ControlStructures.ControlSignature.SpaceAfterKeyword sniff, so I'm not sure if we should include it in the documentation for this sniff.

I'm all for removing squiz rules from the PSR12 ruleset, and just modifying the ControlStructuresSpacing sniff to include all the checks as in the PSR-12 documentation for control structures, but I think that would be something for PHPCS v4.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You are 100% correct! I thought this sniff was checking that too, but you are right, it does not. The updated standards description from commit a1795c1 confused me as that _does_mention the space after the control structure keyword.

In other words: No, there should not be a code sample for space after keyword, but the first <standard> block will need to be updated to remove the mention of the spacing after the keyword.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And this bit ", and one space between the closing parenthesis and the opening brace" will also need to be removed as that is also not checked via this sniff.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, you're right about these. Will fix them now 👍🏼

}
]]>
</code>
</code_comparison>
<code_comparison>
<code title="Valid: No space before the closing parenthesis in a single-line condition.">
<![CDATA[
if <em>(</em>$expr) {
}
]]>
</code>
<code title="Invalid: Space before the closing parenthesis in a single-line condition.">
<![CDATA[
if ($expr<em> </em>) {
}
]]>
</code>
</code_comparison>
<standard>
<![CDATA[
The body of the multi-line control structure must be indented once, placing the body on the next line after the opening brace.
]]>
</standard>
<code_comparison>
<code title="Valid: First expression of a multi-line control structure condition block is on the line after the opening parenthesis.">
<![CDATA[
while (
<em>$expr1</em>
&& $expr2
) {
}
]]>
</code>
<code title="Invalid: First expression of a multi-line control structure condition block is on the same line as the opening parenthesis.">
<![CDATA[
while (<em></em>$expr1
&& $expr2
) {
}
]]>
</code>
</code_comparison>
<code_comparison>
<code title="Valid: Each line in a multi-line control structure condition block indented at least once. Default indentation is 4 spaces.">
<![CDATA[
while (
<em> </em>$expr1
<em> </em>&& $expr2
) {
}
]]>
</code>
<code title="Invalid: Some lines in a multi-line control structure condition block not indented correctly.">
<![CDATA[
while (
<em></em>$expr1
&& $expr2
<em> </em>&& $expr3
) {
}
]]>
</code>
</code_comparison>
<standard>
<![CDATA[
The closing parenthesis of the multi-line control structure must be on the next line after the body, indented to the same level as the start of the control structure.
]]>
</standard>
<code_comparison>
<code title="Valid: The closing parenthesis of a multi-line control structure condition block is on the line after the last expression.">
<![CDATA[
while (
$expr1
&& $expr2
<em>)</em> {
}
]]>
</code>
<code title="Invalid: The closing parenthesis of a multi-line control structure condition block is on the same line as the last expression.">
<![CDATA[
while (
$expr1
&& $expr2<em>)</em> {
}
]]>
</code>
</code_comparison>
<code_comparison>
<code title="Valid: The closing parenthesis of a multi-line control structure condition block is indented to the same level as start of the control structure.">
<![CDATA[
while (
$expr1
&& $expr2
<em>)</em> {
}
]]>
</code>
<code title="Invalid: The closing parenthesis of a multi-line control structure condition block is not indented to the same level as start of the control structure.">
<![CDATA[
while (
$expr1
&& $expr2
<em> </em>) {
}
]]>
</code>
</code_comparison>
</documentation>