Naming
How to name namespaces, types and services so that a name says what the code is and who owns it. Code Organization covers where code goes; this page covers what it is called.

Recommendation, not a requirement. The packages work without following this convention. It is a rule only for code in the toolkit repository (see Contributing); applications can adopt it, adapt it or skip it. Opting out or adapting explains how.
Why
- Names carry architecture. A suffix or a namespace segment tells a reader the responsibility before they open the file. See layered architecture.
- Consistency with .NET. Plural namespaces and singular types match
System.Collections,System.Diagnostics,Microsoft.Extensions.LoggingandMicrosoft.AspNetCore.Mvc. - No mechanical uniformity. The rules keep names clear; they are not meant to rename everything.
Namespaces
- Use plural nouns for namespace segments and singular nouns for types.
- Reflect architectural ownership and responsibility; avoid redundant segments.
- Keep namespaces and physical folders aligned (extension classes are the exception, see Extensions).
- Prefer responsibility-specific namespaces where they add clarity; keep
Helpersfor shared helper functions. - Do not invent a namespace distinction only to avoid a name collision; give the type a more descriptive name instead.
Acme.Core.Events.Domain
Acme.Core.Repositories
Acme.Infrastructure.Messaging
Acme.Configuration.Telemetry
Use Exceptions, Extensions, Helpers, UseCases and Services.Aggregates as appropriate.
Type suffixes
Keep a suffix when it communicates an architectural distinction, and leave it off when it adds nothing.
| Suffix | Meaning | Example |
|---|---|---|
Entity |
Identity-bearing domain or persistence entity | CustomerEntity |
Model |
General-purpose representation | CustomerModel |
Dto |
Data transfer representation | CustomerDto |
Dao |
Data access object | CustomerDao |
Record |
Data-centric record or value representation | DomainEventDbRecord |
Options |
Configuration | TelemetryOptions |
Context |
Execution or operational context | ApplicationContext |
Result |
Operation outcome | HealthCheckResult |
- Do not use
Entityas a synonym for “class”. A transient message or a value is not an entity. - Do not remove a representation suffix when it separates types with different responsibilities (
CustomerEntityversusCustomerDto). - Do not append a suffix mechanically when it adds no information.
- Prefer an explicit name when the namespace alone would leave a public API ambiguous.
- Keep names that are already clear:
IUnitOfWork,IStorageRepository,IMessageBrokerPublisher.
Services
Name a service implementation after what it does, with a responsibility-oriented agent noun, preferably ending in -er or -or: Publisher, Worker, Masker, Parser, Serializer, Resolver, Dispatcher, Validator.
- Avoid generic names such as
ManagerorProcessorunless the responsibility is unambiguous. - A service encapsulates one distinct operation or technical responsibility. Business workflows are UseCases instead.
- Repositories always keep the
Repositorysuffix; aggregates are services named<Resource>Aggregate. - Helpers identify their subject or operation, for example
DateHelper.
Summary
| Concern | Convention |
|---|---|
| Namespaces | Plural nouns, aligned with folders |
| Types | Singular nouns |
| Services | Responsibility-oriented agent nouns (Publisher, Validator) |
| Repositories | Repository suffix |
| Entities | Entity suffix when semantically appropriate |
| DTOs, models, DAOs | Dto, Model and Dao suffixes to tell representations apart |
| Helpers | Named after their subject; pure helpers stay static and out of DI |
| Extensions | Extensions suffix, the subject’s namespace |
| UseCases | <Action><Subject>UseCase |
| Aggregates | <Resource>Aggregate under Services/Aggregates/ |
Opting out or adapting
| You want to… | Do this |
|---|---|
| Keep singular namespaces or your own suffixes | Keep them within your solution and write them down in an ADR or AGENTS.md; nothing in the toolkit reads names. |
Keep Service or Entity folders |
Fine inside your own projects; nothing in the toolkit requires them to change. |
What you lose by opting out: names that match the toolkit’s and .NET’s own, so mixed code reads less uniformly and agents need your documented exceptions to follow your style.