Naming is generic where understanding is weak
As conceptual clarity drops, code and design names become broader and more vague.
- Where you see this
utility layersservice classesintegration glueshared libraries
- Not necessarily a problem when
- the abstraction is intentionally generic and tightly scoped
- Often mistaken for
- good naming alone fixes bad boundaries
- Time horizon
- medium-term
- Best placed to act
module ownertech lead
The signal
What you would actually notice
Weak naming hides weak modeling. It reduces shared understanding and makes refactoring harder.
Field observation
Names like Manager, Processor, Util, Handler, Common, Core, Engine appear where domain meaning should be stronger.
Also observed
- We have DataManager, SyncManager, RuleEngine, and CommonProcessor.
- It is generic because we might reuse it later.
Primary reading
What it usually indicates
Most likely underlying patterns when this signal shows up. Not a diagnosis, a starting hypothesis.
Usually indicates
Most likely underlying patterns when this signal shows up.
- unclear domain concepts
- responsibility overlap
- fear of committing to a real model
Stakes
Why it matters
Weak naming hides weak modeling. It reduces shared understanding and makes refactoring harder.
Inspection
What to check next
Deliberate steps to confirm or disconfirm the primary reading above. Not a checklist. An order of inspection.
- neighboring classes or modules
- domain language in product or business docs
- change reasons for the generic component
Diagnostic questions
Questions to ask the team, or yourself, before concluding anything.
- Could a non-author explain what this component is for?
- Is this name hiding multiple responsibilities?
- Does the domain have better words than the code does?
Progression
Under the signal
Where this pattern tends to come from, what's holding it up, and where it goes if nothing changes.
Leading indicators
What tends to show up first.
- different files use the same vague nouns for different jobs
- code reviews rarely challenge names
- domain experts do not recognize terms used in code
Common root causes
What is usually sitting under the signal.
- shallow modeling
- premature abstraction
- infrastructure language dominating domain language
Likely consequences
What happens if nothing changes.
- miscommunication
- scope creep
- harder onboarding
Look-alikes
Not what it looks like
Patterns that can be mistaken for this signal, and 'fix' attempts that make it worse.
- good naming alone fixes bad boundaries
Anti-patterns when responding
Responses that feel sensible and usually make the underlying pattern worse.
- renaming without changing structure
- using generic nouns as a substitute for design clarity
Context
Context and ownership
Where this signal surfaces, who sees it first, who can actually act, and how much runway there usually is before escalation.
Where it shows up
- utility layers
- service classes
- integration glue
- shared libraries
Who sees it first
Before it escalates.
- new joiners
- reviewers
- domain-aware engineers
Who can move on it
Not always the same as who notices it.
- module owner
- tech lead
medium-term
How much runway there usually is before the signal hardens into the underlying pattern.
AI impact
AI effects on this signal
How AI-assisted and AI-driven workflows tend to amplify or hide this signal.
AI amplifies
Ways AI tooling tends to make this signal louder or more common.
- AI tends to generate safe generic names when the model lacks strong domain signals.
AI masks
Ways AI tooling tends to hide this signal, so it keeps growing under the surface.
- Consistent generic naming can look orderly and intentional.
Relationships
Connected signals
Related failure modes, decisions behind the signal, response playbooks, and neighboring red flags.