WordPress Coding Standards

5 min read

The Official WordPress Style Guide may be intimidatingly extensive, but it offers valuable insights for producing code that is easy to maintain and work with. You don’t need to memorize every detail, but it is important to familiarize yourself with key sections, particularly the highlights and the section on naming and referring to files. This will help you write code that aligns with the wider WordPress ecosystem while keeping internal practices cohesive.

Why Coding Standards Matter

Following coding standards is not just about adhering to arbitrary rules—it’s about fostering collaboration and long-term project health. When everyone follows the same conventions, it becomes much easier to:

  • Avoid common errors: Coding standards highlight patterns that often lead to bugs or performance issues.
  • Enhance readability: Clean and consistent code is easier to read and understand, even for developers unfamiliar with a particular section.
  • Improve maintainability: If code looks consistent across the project, anyone on the team can quickly jump in, understand, and modify it, no matter when it was written or by whom.

By adopting these guidelines, we ensure that code within the project appears as if it were created by a single person, thus making collaboration smoother and reducing technical debt over time.

Language-Specific Standards

Each language has its own best practices, and WordPress provides specific guidelines for the key languages we use:

These are living documents, and keeping up with them ensures we avoid common pitfalls and write code that integrates well with the WordPress ecosystem.

Utilizing Linters and Code Review Tools

To help enforce adherence to coding standards automatically, we incorporate linters into our workflow. Linters analyze your code in real-time and alert you to violations of style rules. This allows you to fix issues as you write, saving time in code reviews and minimizing errors that may otherwise slip into production.

For PHP, I use PHP CodeSniffer, configured to check for WordPress Coding Standards. To set this up:

  1. Install PHP_CodeSniffer and the WordPress Coding Standards ruleset.
    • If you’re on a MacOs, I like to use Homebrew to manage this package.
      1. Update Homebrew using brew update
      2. Install PHP_CodeSniffer using brew install php-code-sniffer. This installs the phpcs and phpcbf binaries into Homebrew’s bin directory, which is already on your PATH on a typical setup.
      3. Verify it works with phpcs --version and phpcbf --version.
      4. You should see the PHP_CodeSniffer version print out, confirming a global install. You’re done; you can now run phpcs from any project.
  2. Integrate it into your preferred code editor (e.g., Visual Studio Code, PhpStorm) for live feedback as you code.

With these tools, not only will you receive suggestions while writing code, but you can also scan entire directories and even automatically fix some style violations. Use the following CLI commands to scan or fix your code:

$: phpcs templates/example.php   # To scan for style violations
$: phpcbf templates/example.php  # To automatically fix violations

If you are unfamiliar with setting up PHP_CodeSniffer, check out this video guide.

Alternative phpsab Option

An alternative to the PHP CodeSniffer Extension is the “PHP Sniffer & Beautifier (phpsab)” extension.

Advantages:

  • Provides both linting and formatting directly in the editor.
  • Easier for developers who prefer auto-fixing issues while coding (e.g., on save).

Disadvantages:

  • Less precise than using phpcs directly in the terminal.
  • Additional configuration overhead compared to phpcs alone.
  • The lead developer has mostly stepped away, though some other maintainers have stepped up and last updated this to v0.0.20 on 11/14/2024

Here’s a brief tutorial on setting this up.

Just make sure to only use one of those extensions since they have a lot of overlap and will cause some errors if you haven’t configured them carefully.

gotcha: one of the things I needed to debug when I first set this up was conflicting settings between my editor’s default formatting rules and PHP_CodeSniffer’s rules. This was evident because my editor was automatically formatting the code on save (via Prettier), and it was overriding PHP_CodeSniffer’s rules. After installing PHP Intelephense, I added the following to settings.json (for my user) and this got it working:

"editor.formatOnSave": true,
"[php]": {
    "editor.defaultFormatter": "wongjn.php-sniffer-beautifier"
},

Enforcing Consistent Style with Husky

To further ensure consistency, we use Husky, a tool that hooks into Git workflows to enforce code quality checks before commits. By adding linting tools like PHP_CodeSniffer or ESLint (for JavaScript) to Husky, you can prevent commits that violate coding standards from being pushed to the repository.

Setting Up Husky

  1. Install Husky: Run the following command to add Husky to your project
    npm install husky --save-dev
  2. Set Up Git Hooks: Husky allows you to add Git hooks that run checks at various stages of the Git process. We primarily focus on the pre-commit and pre-push hooks to run linters and ensure all code adheres to our standards.To add a pre-commit hook, run:
    npx husky add .husky/pre-commit "npm run lint"
    This will prevent any commit from being made if the linter detects style violations.
  3. Customizing Your Linter: Depending on the language, you can configure Husky to run multiple checks. For example, you can set it up to run PHP_CodeSniffer for PHP files, ESLint for JavaScript, and Stylelint for CSS:
    npx husky add .husky/pre-commit "npm run phpcs && npm run eslint && npm run stylelint"
  4. Testing Linting Before Push: You can also configure Husky to run the linter before a git push is allowed
    npx husky add .husky/pre-push "npm test"
    This way, the entire project is scanned and tested before any code is pushed, preventing broken or inconsistent code from entering the repository.

Read more in the official docs.

Developing your own Coding Standards

Once you’ve got the basics of how this works you can set up your own personal coding standards for linters. Here are some public examples: