Clean Code Practices

Since we use Bootstrap/Bootscore as a starter for many of our themes and we operate inside of WordPress, we should follow similar language style conventions to make things uniform.

Clean Code Practices 🛁

Here’s a good summary of Robert Martin’s book, Clean Code.

• Add type declarations to function arguments in PHP
• Comment your code according JSDoc/PHPDoc syntax so VS Code’s Intelephense can pick up function description and argument expectations on hover.
• ⚠️ Function/Variable names should be descriptive enough that the code reads like good documentation ⚠️
  • Don’t be lazy about this, as comments are prone to grow stale or be moved separately from their related functions.
• All names, regardless of which language we’re writing in, should be in English and not Choctaw, as none of the developers (at the time of writing) are fluent Choctaw speakers.

The Ternary Operator

Read more about the ternary operator.

PHP 🐘

General Conventions

• If WPCS is giving you a red squiggly line, change your code to get rid of it! // phpcs:ignore should almost never be used.
• Comment your files! Copying and Pasting without an edit is poor practice and makes it harder to keep track of where you are—especially if you’re copying a bootscore/plugin file to make changes to.
• Always prefer snake_case for function/variable names over camelCase or kebab-case (WPCS will squiggle this, anyways).
• Place as much PHP in the top of a file as possible so the the HTML can remain, largely, pure HTML.
  • If the top of a file becomes inordinately long (e.g. 20+ lines), consider trying to refactor into something else.
  • Stay in PHP as long as you can (e.g. your top-matter should only have the opening <?php and closing tag at the end.
  • The last line should generally be get_header('some_header') ?> whenever possible, to signify to the author that we are breaking into the HTML matter.

Breaking Changes 🚨

Prefer single line statements. Ternary operators can be used if it increases readability (i.e. keeps things on one line).

Mixed Markup (HTML + PHP)

• In the case of single-line HTML + PHP, consider using string literals to enhance readability and reduce silly errors (e.g. a floating > after dropping in-and-out of PHP and HTML for an <a> tag

Refactoring

• Theme functions and plugin-like files (e.g. CPT Declarations) should live inside inc/ folder and appropriate sub-directories.

CSS 💄

General Conventions

• Prefer SCSS over pure CSS
• Always uses kebab-case, never camelCase for class/id names
• Override Bootstrap variables
• Use Bootstrap utility classes wherever possible
• Use @use over @import wherever possible
• Bootstrap is, unfortunately, built on top of @import statements for simple overrides, but this is poor practice as @import will be deprecated. Typically, I (KJ) have found that I only really need the breakpoints mixins, and that is easy enough to copy into my own mixins.scss file to reuse with the @use rule. Also, since Bootstrap is open-source, it’s totally legal to do so 🙂

File Architecture 📘

• The top-level scss file (named either main.scss should @use all components that are global to a site. The styles/pages directory should @use styles that simply override globals or contain page-specific styles.
• The src/styles folder is the root directory for all SCSS/CSS files, and should utilize the 7-1 Architecture pattern.
  • We may not have all 7 folders, but this convention is still helpful to use, especially when telling Webpack what to look for.

Enqueuing Styles (with PHP 🐘)

global.css should be enqueued dist/css folder as second-to-last in the chain.

Enqueue Order:

1. /dist/vendors/*.css
2. dist/css/global.css
3. style.css (required by WordPress)

Each php (🐘) page should enqueue its own css (💄) on the line before get_header('some-header') ?> so the page only ships with the css it needs. Thus, the Enqueue Order might be understood as:

1. vendors.css
2a. dist/css/global.css
2b. dist/css/page/page.css
3. style.css (required by WordPress)

Where 2b is dynamically injected on each page by the server.