116 lines
5.3 KiB
Markdown
116 lines
5.3 KiB
Markdown
# Coding Conventions
|
|
|
|
**Analysis Date:** 2026-05-07
|
|
|
|
## Naming Patterns
|
|
|
|
**Files:**
|
|
- WordPress entry/template names follow WordPress conventions: `index.php`, `functions.php`, `header.php`, `footer.php`, `comments.php`.
|
|
- MU plugin loader and implementation use descriptive plugin paths: `wp-content/mu-plugins/cookie-notice-pro-loader.php`, `wp-content/mu-plugins/cookie-notice-pro/cookie-notice-pro.php`.
|
|
- Custom assets use descriptive names: `wp-content/themes/hello-elementor/assets/css/custom.scss`, `wp-content/themes/hello-elementor/assets/css/custom.css`, `wp-content/mu-plugins/cookie-notice-pro/assets/cookienoticepro.script.js`.
|
|
- Third-party plugin file naming varies by vendor; do not use vendor files as project style unless working inside that plugin intentionally.
|
|
|
|
**Functions:**
|
|
- WordPress theme functions use prefixed snake_case, e.g. `hello_elementor_setup()` in `wp-content/themes/hello-elementor/functions.php`.
|
|
- Site-specific MU plugin functions use `cnp_*` prefix, e.g. `cnp_render_gtm_noscript()` in `wp-content/mu-plugins/cookie-notice-pro/cookie-notice-pro.php`.
|
|
- New project-owned PHP functions should use a clear prefix and WordPress-style snake_case.
|
|
|
|
**Variables:**
|
|
- PHP variables follow WordPress/PHP conventions: `$lower_snake_case` where applicable.
|
|
- Constants use uppercase names; example: `CNP_GTM_ID` in `wp-content/mu-plugins/cookie-notice-pro/cookie-notice-pro.php`.
|
|
|
|
**Types:**
|
|
- Hello Elementor theme classes use namespaces and PascalCase class names, e.g. `HelloTheme\Modules\AdminHome\Components\Ajax_Handler` in `wp-content/themes/hello-elementor/modules/admin-home/components/ajax-handler.php`.
|
|
- Most site-owned custom code is procedural WordPress PHP rather than class-based.
|
|
|
|
## Code Style
|
|
|
|
**Formatting:**
|
|
- Project guidance in `CLAUDE.md` says to use WordPress Coding Standards for PHP, JS, and CSS.
|
|
- `wp-content/themes/hello-elementor/functions.php` follows WordPress spacing style such as `if ( ! defined( 'ABSPATH' ) )`.
|
|
- `wp-content/mu-plugins/cookie-notice-pro/cookie-notice-pro.php` uses 4-space indentation and less consistent WordPress spacing such as `if (!defined('ABSPATH'))`.
|
|
- New project-owned PHP should prefer WordPress Coding Standards even when older custom code is mixed.
|
|
- SCSS in `wp-content/themes/hello-elementor/assets/css/custom.scss` uses nested SCSS, Elementor-oriented selectors, and mobile breakpoints.
|
|
- `wp-content/themes/hello-elementor/assets/css/custom.css` is compiled/minified and includes a source map reference.
|
|
|
|
**Linting:**
|
|
- No root `.eslintrc*`, `.prettierrc*`, `phpcs.xml*`, `.editorconfig`, `composer.json`, or `package.json` detected.
|
|
- No project lint command detected.
|
|
|
|
## Import / Dependency Organization
|
|
|
|
**PHP Loading:**
|
|
- Use WordPress hooks (`add_action`, `add_filter`) for lifecycle integration.
|
|
- Enqueue frontend styles/scripts from PHP rather than hardcoding tags.
|
|
- MU plugin loading is done through `wp-content/mu-plugins/cookie-notice-pro-loader.php`.
|
|
|
|
**Path Aliases:**
|
|
- Not applicable; no project-owned module bundler or PHP autoload setup detected.
|
|
|
|
## Error Handling
|
|
|
|
**Patterns:**
|
|
- WordPress/PHP handles most runtime errors.
|
|
- Use guard checks such as `defined( 'ABSPATH' )` in PHP entry files.
|
|
- Escape frontend output with WordPress helpers (`esc_js`, `esc_attr`, etc.) as seen in `wp-content/mu-plugins/cookie-notice-pro/cookie-notice-pro.php`.
|
|
|
|
**Expected Practice:**
|
|
- Avoid breaking public pages/forms if optional assets or config are missing.
|
|
- In frontend JS, guard JSON parsing and cookie access before use.
|
|
|
|
## Logging
|
|
|
|
**Framework:**
|
|
- No dedicated logger detected.
|
|
- Browser console logging exists in `wp-content/mu-plugins/cookie-notice-pro/assets/cookienoticepro.script.js`.
|
|
|
|
**Patterns:**
|
|
- Avoid new production console noise unless it is behind a debug flag.
|
|
|
|
## Comments
|
|
|
|
**When to Comment:**
|
|
- Explain business/compliance decisions, especially consent/GTM behavior.
|
|
- Avoid comments that restate obvious WordPress API usage.
|
|
|
|
**JSDoc/TSDoc:**
|
|
- Not used as a project standard.
|
|
|
|
**TODO Comments:**
|
|
- Many TODOs exist in WordPress core and third-party plugins; do not treat them as project-owned debt.
|
|
- No meaningful custom TODO/FIXME debt was found in the MU plugin or theme customizations.
|
|
|
|
## Function Design
|
|
|
|
**Size:**
|
|
- Keep new custom PHP functions focused around a WordPress hook or one behavior.
|
|
- Extract helpers when frontend consent/form logic grows.
|
|
|
|
**Parameters:**
|
|
- Prefer explicit arguments and small option arrays for custom helpers.
|
|
|
|
**Return Values:**
|
|
- Use early returns for guard conditions.
|
|
- Ensure frontend helpers handle missing/malformed cookies without throwing.
|
|
|
|
## Module Design
|
|
|
|
**Exports:**
|
|
- WordPress hooks/functions are the main module boundary in custom code.
|
|
- For new site-owned behavior, prefer a dedicated MU plugin or project-owned plugin over editing third-party plugin files.
|
|
|
|
**Barrel Files:**
|
|
- Not applicable.
|
|
|
|
## Editing Boundaries
|
|
|
|
- Do not edit `wp-admin/` or `wp-includes/`.
|
|
- Do not edit third-party plugin code in `wp-content/plugins/` unless explicitly required.
|
|
- Prefer custom work in `wp-content/themes/hello-elementor/assets/`, `wp-content/themes/hello-elementor/functions.php`, or a site-owned plugin/MU plugin.
|
|
- Confirm file encoding before editing Polish copy in `wp-content/mu-plugins/cookie-notice-pro/`; some text appears mojibake.
|
|
|
|
---
|
|
|
|
*Convention analysis: 2026-05-07*
|
|
*Update when patterns change*
|