# 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*