The real payoff of WordPress coding standards

Propose adopting a coding standard and the first reply is usually “but it works fine as it is”. Which is true — conforming to a standard does not make code faster, and bugs do not evaporate. The payoff is somewhere else entirely: formatting stops being discussed in review.

The gain is attention, not tidiness

Review in a repository without a standard goes like this. “Your indentation differs here.” “I would put that brace on the next line.” “Shall we agree a naming rule?” All of it is an exchange of preferences, and even when settled it restarts in the next file.

Worse, that conversation spends attention first. Nobody reads code with full concentration for very long, and if the opening minutes go on whitespace and braces, less is left for what actually matters: does this change match the intent, is there an edge case nobody handled.

That is where the real value sits. Which convention wins is unimportant; that one has been chosen is everything. And whatever has been chosen should not be raised by a person — when the tooling raises it, nobody’s attention is spent at all.

What the standard actually settles

The WordPress coding standards cover PHP, HTML, CSS and JavaScript; in daily work it is the PHP rules that fire. They fall into three groups.

Formatting — tabs for indentation, spaces inside parentheses, short array syntax. This group is auto-fixable, so people barely touch it.

Naming — lowercase underscores for functions and variables, capitalised class names, file naming. Project prefix rules are usually layered on here.

Safety — this group is the real reason to adopt the standard. The ruleset flags missing output escaping, unsanitised input, direct $wpdb queries without prepare(), and missing nonce verification. If the formatting rules made this look like a matter of taste, this group settles the question.

Let the tooling enforce it

Setup is short. Install the ruleset as a development dependency and commit a configuration file.

composer require --dev wp-coding-standards/wpcs 
    dealerdirect/phpcodesniffer-composer-installer

vendor/bin/phpcs   # check
vendor/bin/phpcbf  # fix automatically

Committing the ruleset file (phpcs.xml.dist) is the part people skip. If the configuration exists only in individual editors, everyone checks against slightly different rules — and then you do not have a standard, you have several opinions about one.

<?xml version="1.0"?>
<ruleset name="Acme">
    <file>.</file>
    <exclude-pattern>vendor/*</exclude-pattern>
    <exclude-pattern>node_modules/*</exclude-pattern>

    <rule ref="WordPress"/>

    <config name="minimum_wp_version" value="6.0"/>
    <rule ref="WordPress.WP.I18n">
        <properties>
            <property name="text_domain" type="array" value="acme"/>
        </properties>
    </rule>
</ruleset>

Then wire it into three places. In the editor it shows up as you type; in a commit hook it checks only the changed files and stays fast; in CI it becomes the gate nobody can walk around. All three is ideal, but if you pick one, pick CI — the others are personal configuration and personal configuration goes missing.

Adopting it without a giant rewrite

Switch the standard on over an existing codebase and you get thousands of warnings. Trying to clear them all produces one enormous change that cannot be reviewed, and mixing it with behaviour changes turns it into an incident.

The practical order runs like this. Apply the check to new code only at first — configure CI to inspect changed files and you can start without touching anything historical. Next, take just the auto-fixable formatting rules and clean one directory at a time in pure formatting commits, never mixed with behaviour. Finally, turn the remaining safety warnings into a list and work through it individually, because those may be genuine defects rather than style and should not be bulk-processed.

When a rule genuinely needs an exception, record the reason with it. Suppression comments without justification multiply, and once they do the check stops being believed.

A good companion is a PHP compatibility check: declare the lowest version you support and newer syntax gets caught before deployment rather than after.

Wiring these checks into CI is covered in the From local to production series, and related writing sits in the development workflow archive. If the accumulated code needs its quality and its vulnerabilities addressed together, PHP source clean-up is part of our optimization program.