1.9 KiB
1.9 KiB
Shared Language
Use this page to keep the repository's ubiquitous language stable. It is the project-wide glossary for terms that should mean one thing everywhere in design artifacts, code, tests, and reviews.
Why this exists
Naming inconsistency creates design inconsistency. When the same concept is called three different things, reviewers and LLMs start inventing distinctions that are not real. A stable shared language improves design quality, review quality, and implementation consistency.
This file is for project-wide terms. Feature-specific naming choices should also be recorded in the relevant design artifact.
How to use it
- Add terms that appear across multiple features or modules.
- Prefer short domain definitions over implementation detail.
- Record preferred terms and rejected synonyms.
- Update this file when the team decides one name should win.
- Keep the grammar consistent with the naming rules in
../explanation/naming-for-domain-modeling.md.
Core grammar
- Commands: imperative intents such as
LoadPackage - Events: past-tense facts such as
PackageLoaded - States / Objects: domain nouns such as
LoadingTruck - Workflows: verb-noun names such as
loadPackage - Policies: decision-oriented names such as
decideLoadEligibility
Project-wide glossary template
| Term | Meaning | Use this, not that | Notes |
|---|---|---|---|
<PreferredTerm> |
<Short domain meaning> |
<PreferredTerm> not <RejectedSynonym> |
<Optional note> |
<PreferredTerm> |
<Short domain meaning> |
<PreferredTerm> not <RejectedSynonym> |
<Optional note> |
Review questions
- Would a domain expert recognize these terms?
- Are the same concepts named consistently across story, events, model, code, and tests?
- Are we accidentally using programmer words where domain words should exist?
- Have we documented which synonym is preferred when multiple names are plausible?