When it comes to writing code, style matters.
Nearly every programming language, framework, and CMS has their own code style standards that they urge you to follow. For example, Symfony and Drupal each have their own code style standards, and similarly WordPress has its own standards. I wouldn’t ask a Drupal engineer to practice WordPress standards on a Drupal project, just as a WordPress engineer shouldn’t be asked to practice Symfony standards on a WordPress project. Generally speaking, follow the standards set forth by the language/framework/CMS that you are working in.
I typically integrate PHP Code Sniffer (PHPCS) with WordPress Coding Standards (WPCS) directly into my IDE (PhpStorm). Partially this helps me avoid mistakes while I write code, and partially it makes life easier for any WordPress developer (including myself) who has to work with code I’ve written in the future. A number of other text editors and IDEs offer similar integrations with PHPCS. WPCS maintains some documentation on their GitHub wiki about using WPCS with other editors.
However, I do not advocate that you should follow all of the rules in all circumstances. I personally do not adhere 100% to WPCS in my projects. There are some sniffs that I exclude because they hinder some aspect of development, or simply don’t make sense for a client project.
Fortunately, if you need to customize or disable one or more sniffs for your own project, you can use a custom PHPCS ruleset do so. The PHPCS Github wiki’s Annotated Ruleset is a great resource for getting started with PHPCS ruleset configuration, and WPCS maintains a page on their GitHub wiki that lists customizable sniff properties. And of course, you can always disable specific sniffs entirely from your ruleset.
As an example, I do not name class files “class-file-name.php” as WPCS would generally require. I write class names and class file names according to PSR-4 standards, because I use Composer for dependency management and autoloading. Disabling that particular “sniff” can be accomplished with a little bit of XML in the PHPCS ruleset.
<rule ref="WordPress.Files.FileName">
<properties>
<property name="strict_class_file_names" value="false"/>
</properties>
<exclude name="WordPress.Files.FileName.NotHyphenatedLowercase"/>
</rule>As another example, WordPress typically frowns upon “precision alignment,” but when I’m working with front-end developers, they often like to line up attributes on HTML elements in partials to make the markup easier to read.
If you want to maintain a list of elements which the PrecisionAlignment sniff should ignore, you can do so in your PHPCS ruleset with the ignoreAlignmentTokens property.
<rule ref="WordPress.WhiteSpace.PrecisionAlignment">
<properties>
<property name="ignoreAlignmentTokens" type="array">
<element value="T_COMMENT"/>
<element value="T_INLINE_HTML"/>
</property>
</properties>
</rule>Or, if you prefer (as I generally do), you can disable the PrecisionAlignment sniff entirely.
<rule ref="WordPress">
<exclude name="WordPress.WhiteSpace.PrecisionAlignment"/>
</rule>If you don’t want to start a ruleset from scratch, there’s a phpcs.xml.dist ruleset included in the Underscores starter theme that you can customize for your own theme development, it is also included if you use WP-CLI’s wp scaffold _s command to scaffold your theme. Similarly, WP-CLI can generate a phpcs.xml.dist ruleset for your plugin development using the wp scaffold plugin command.
If you write code for WordPress, and you aren’t using PHPCS and WPCS, I would strongly urge you to begin using these tools. They will improve your code quality, make your code easier to read, and generally make my life easier if I need to work on something you wrote. 😃
