Code Quality

Code Quality Standards for Simple History

This skill provides code quality guidelines for the Simple History WordPress plugin, including PHP, CSS, and JavaScript standards, tooling commands, and best practices.

When to Use This Skill

Invoke this skill proactively before writing code to ensure compliance with project standards.

Trigger scenarios:

• Before writing or editing PHP code
• Before writing or editing CSS code
• Before writing or editing JavaScript code
• When running code quality tools (phpcs, phpstan, rector)
• When fixing lint errors or reviewing code style

Quick Reference

PHP Standards

• PHP Version: 7.4+ compatibility required
• WordPress Coding Standards: Official WordPress standards (see phpcs.xml.dist)
• No mb_ functions*: Use standard string functions
• Array syntax: Short syntax [] not array()
• Control structures: Always use curly braces {}, never colon syntax
• Hook prefixes: Always use sh, simplehistory, or simple_history

CSS Standards

• Naming Convention: SuitCSS
• Prefix: sh
• Components: sh-ComponentName (e.g., sh-HelpSection, sh-LogEntry)
• Subparts: sh-ComponentName-subpart (e.g., sh-LogEntry-author)

JavaScript

• Follow @wordpress/scripts conventions
• Text domain: simple-history
• Always use braces for if/else/for/while (no single-line statements)

Detailed Guidelines

PHP Code Style

See php-standards.md for detailed PHP style guide including:

• Happy path last pattern
• Early returns over else
• Ternary operator formatting
• Control structure syntax

Tooling Commands

See tooling.md for:

• phpcs (PHP_CodeSniffer) usage
• phpstan (static analysis) usage
• rector (code modernization) usage
• npm scripts for code quality

CSS Guidelines

See css-standards.md for SuitCSS naming conventions and examples.

JavaScript Guidelines

See js-standards.md for JavaScript code style.

Essential Principles

1. Always escape output - Use WordPress escaping functions
2. Prefix everything - Use sh, simplehistory, or simple_history
3. Follow WordPress conventions - The "WordPress Way"
4. Run quality tools - Use phpcs, phpstan after significant changes

Design Principles

DRY - Don't Repeat Yourself

Extract shared logic when you have actual duplication (3+ occurrences). But don't preemptively create abstractions.

YAGNI - You Aren't Gonna Need It

Don't implement functionality until it's actually needed. Avoid:

• Creating abstractions for hypothetical future use cases
• Building helper functions for one-time operations
• Adding configurability "just in case"
• Designing for requirements that don't exist yet

Together: DRY says extract when you have real duplication. YAGNI says wait until you actually need it. Three similar lines of code is often better than a premature abstraction.

Related Files

• phpcs.xml.dist - PHP_CodeSniffer configuration
• phpstan.neon - PHPStan configuration
• package.json - npm scripts for code quality