luxmed2.pagedev.pl/.paul/codebase/conventions.md

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