Inconsistent Names Smell
debt(d3/e5/b5/t5)
Closest to 'default linter catches the common case' (d3). The detection_hints list phpcs, phpmd, and phpstan — all standard PHP static analysis tools that can flag mixed naming conventions and style violations without specialist configuration. The common case (camelCase vs snake_case mixing) is caught by phpcs with default rulesets, placing this squarely at d3.
Closest to 'touches multiple files / significant refactor in one component' (e5). The quick_fix calls for establishing a naming convention document AND enforcing it with PHP CS Fixer and PHPStan custom rules. The common_mistakes show the problem drifts across the entire codebase (mixed get/fetch/retrieve across different classes, variable naming throughout). This is not a single-line patch — it requires renaming symbols across multiple files and updating all call sites, but stops short of architectural rework.
Closest to 'persistent productivity tax' (b5). The applies_to covers web, cli, and queue-worker contexts — the full breadth of PHP application types. As noted in why_it_matters, every developer reading the code must stop and verify whether naming differences are intentional. The common_mistakes confirm the inconsistency drifts in gradually and touches many work streams, imposing an ongoing cognitive tax on all contributors without being quite as load-bearing as a b7 architectural choice.
Closest to 'notable trap (a documented gotcha most devs eventually learn)' (t5). The misconception field states explicitly that developers treat naming inconsistencies as cosmetic with no functional impact — but they cause real bugs when developers assume methods behave identically based on similar names. This is a well-known, documented gotcha in the code-quality community that most developers eventually recognize, but it contradicts a common beginner intuition, placing it at t5.
Also Known As
TL;DR
Explanation
Inconsistent naming is among the most pervasive readability problems. It manifests as: the same concept named differently across files (Customer vs Client vs User), similar concepts with indistinguishable names (processData vs handleData vs manageData), and mixed naming conventions (camelCase and snake_case in the same codebase). In DDD terms this violates Ubiquitous Language — code should use the same vocabulary as domain experts. The fix: establish a naming glossary, document it, enforce it in code review, and use PHP_CodeSniffer or PHPStan custom rules to catch drift automatically.
Common Misconception
Why It Matters
Common Mistakes
- Mixing get/fetch/retrieve/find for the same operation across different classes.
- Using both $userId and $user_id in the same codebase — pick snake_case or camelCase and stick to it.
- Boolean properties named without is/has/can prefix — isActive is clearer than active or status.
- Not enforcing naming conventions in code review or a linter — inconsistency drifts in gradually.
Code Examples
// Same concept named differently throughout the codebase
function getUser(int $id): User {}
function fetchCustomer(int $id): User {} // same thing, different name
function retrieveMember(int $id): User {} // same thing again
$userId = 1;
$customerId = 1; // same concept — different variable names// Pick one name per concept and use it everywhere
// Add a glossary to CONTRIBUTING.md:
// user — authenticated person with an account
// order — a placed purchase
// product — an item for sale
function findUser(int $id): User {}
// Always 'find' for DB lookup, always 'User' as the entity name
// Enforce with PHPStan custom rules or naming conventions in .editorconfig