Introduction
Given that the PER coding styles were released 8 days ago, and we've made progress in updating the coding standards a bit in the last few months - markdown updates, update some phrasing, removed outdated references, updated examples (still pending in PR #92), I thought that it wouldn't be a bad idea to give some proper structure to the PHP WordPress Coding Standards (PHP WPCS).
By structure, I mean grouping the currently disjointed parts of the CS into some logical groups, like what PER standards (which are just PSR-12 standards at the moment) are doing.
Current status
Currently, we have the following sections
Single and Double Quotes
Indentation
Brace Style
Use `elseif`, not `else if`
Declaring Arrays
Closures (Anonymous Functions)
Multiline Function Calls
Regular Expressions
Opening and Closing PHP Tags
No Shorthand PHP Tags
Remove Trailing Spaces
Space Usage
Formatting SQL statements
Database Queries
Naming Conventions
Only one object structure (class/interface/trait) per file
Self-Explanatory Flag Values for Function Arguments
Interpolation for Naming Dynamic Hooks
Ternary Operator
Yoda Conditions
Clever Code
Error Control Operator `@`
Don't `extract()`
The PER style has the following main sections:
Overview
General
Declare Statements, Namespace, and Import Statements
Classes, Properties, and Methods
Control Structures
Operators
Closures
Anonymous Classes
With subsections it looks like this:
2. General
2.1 Basic Coding Standard
2.2 Files
2.3 Lines
2.4 Indenting
2.5 Keywords and Types
3. Declare Statements, Namespace, and Import Statements
4. Classes, Properties, and Methods
4.1 Extends and Implements
4.2 Using traits
4.3 Properties and Constants
4.4 Methods and Functions
4.5 Method and Function Arguments
4.6 abstract, final, and static
4.7 Method and Function Calls
5. Control Structures
5.1 if, elseif, else
5.2 switch, case
5.3 while, do while
5.4 for
5.5 foreach
5.6 try, catch, finally
6. Operators
6.1. Unary operators
6.2. Binary operators
6.3. Ternary operators
7. Closures
8. Anonymous Classes
which is a lot more structured and clear in my opinion.
Proposal
The proposal is to have the following grouping in the PHP WPCS:
General
Opening and Closing PHP Tags
No Shorthand PHP Tags
Brace Style
Single and Double Quotes
Multiline Function Calls
Naming and declarations
Naming Conventions
Interpolation for Naming Dynamic Hooks
Declaring Arrays
Control structures
Use `elseif`, not `else if`
Whitespace
Space Usage
Indentation
Remove Trailing Spaces
Object-oriented programming
Only one object structure (class/interface/trait) per file
Operators
Ternary Operator
Database
Database Queries
Formatting SQL statements
Closures (Anonymous Functions)
Best recommendations
Regular Expressions
Self-Explanatory Flag Values for Function Arguments
Clever Code
Yoda Conditions
Error Control Operator `@`
Don't `extract()`
This will give a better structure - knowing where things should be located will help find what you need quickly, as well as prepare for the addition of more modern PHP constructs defined in the make post.
The content inside the existing standards will stay the same, so this is just a grouping change (adding new chapters and putting the other parts inside correct chapters).
Please let me know if you think that some sections belong in other chapters, or if you think that the chapters themselves need a better name.
CC @GaryJones @ntwb @jrfnl