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_ or udit_ 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(), or wp_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 wp object 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, not white).
• 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.).

1. VS Code: Install the vscode-phpcs and ESLint extensions.
2. Configuration: The project includes .eslintrc.js, .stylelintrc, and phpcs.xml.dist files which will be automatically detected by your editor to provide real-time feedback.