Coding Standards
Overview
To maintain consistency, security, and readability across the codebase, this project strictly adheres to the official WordPress Coding Standards. All contributions must pass automated linting checks for PHP, JavaScript, and CSS before being merged.
PHP Coding Standards
We use PHP_CodeSniffer (PHPCS) with the WordPress ruleset (including Core, Docs, and Extra).
Usage
To check your code for compliance, run the following command from the root directory:
composer lint:php
To automatically fix common formatting errors, use the PHP Code Beautifier:
composer format:php
Key Requirements
- Naming Conventions: Use lowercase snake_case for variables, functions, and file names (e.g.,
my_function_name()). - Prefixing: All public functions, classes, and global variables must be prefixed with
ua_orudit_to prevent namespace collisions. - Sanitization & Escaping: All input data must be sanitized, and all output data must be escaped using WordPress functions like
esc_html(),esc_attr(), orwp_kses().
/**
* Correct example of a public function with escaping.
*/
function ua_display_user_greeting( $name ) {
// Sanitize input if it were coming from a request
$safe_name = sanitize_text_field( $name );
// Output with escaping
printf(
'<h2>%s</h2>',
esc_html( $safe_name )
);
}
JavaScript and CSS Standards
JavaScript and CSS follow the standards defined in the @wordpress/scripts package. This ensures compatibility with the Block Editor (Gutenberg) and modern browser requirements.
Usage
To lint your JavaScript and CSS files, run:
npm run lint
To automatically fix linting issues:
npm run format
JavaScript Guidelines
- ESNext: We use modern JavaScript syntax. Ensure your code is processed through the build pipeline.
- Dependency Injection: When using WordPress packages, use the global
wpobject or standard ES6 imports if the build step is configured. - Comments: Use JSDoc for all function definitions.
/**
* Handles the toggle event for the custom navigation.
*
* @param {Event} event The click event object.
* @return {void}
*/
const handleToggle = ( event ) => {
event.preventDefault();
// Implementation details...
};
CSS and Formatting
We utilize Stylelint to enforce the WordPress CSS Coding Standards.
- Structure: Use BEM (Block Element Modifier) naming conventions for custom components.
- Colors: Always use hex codes or CSS variables; avoid named colors (e.g., use
#ffffff, notwhite). - Indentation: Use tabs for indentation to match WordPress core.
/* Example of compliant CSS */
.ua-custom-card {
background-color: #f0f0f0;
margin: 1rem 0;
}
.ua-custom-card__title {
font-weight: 700;
line-height: 1.5;
}
Editor Integration
For the best development experience, it is highly recommended to integrate these standards directly into your IDE (VS Code, PhpStorm, etc.).
- VS Code: Install the
vscode-phpcsandESLintextensions. - Configuration: The project includes
.eslintrc.js,.stylelintrc, andphpcs.xml.distfiles which will be automatically detected by your editor to provide real-time feedback.