This document covers the naming conventions for the code. Some of these contentions are used by the framework and code generation, and as such are required. Others are our recommendations that we find useful for making things clear and structuring the code.
Proto files are named using the
snake_case, as defined by Protobuf. There are several special
kinds of files.
Commands and events reference model entities via their identifiers.
Having typed identifiers makes a model type safe.
Although the framework also supports
Long as valid ID types,
we strongly recommend defining custom ID types like
You can find similar cases in the framework API which has
We found it convenient to define ID types in one file called
A typical project is likely to have more than one Bounded Context, so you
are going to have several
identifiers.proto each residing under the directory with proto
files defining the data model of the corresponding Bounded Context.
Commands are defined in a file which names end with
It can be simply
commands.proto, but usually commands are handled by different entities.
So, it’s convenient to name such a file after the type of the target entity,
for instance, an aggregate:
Similarly to commands, events are defined in files which names has the
Rejection is a special — so to say, “negative” — kind of events supported by the framework.
A rejection is thrown if a command cannot be handled. Think exceptions, but of non-technical flavor.
Similarly to events, rejections are defined in files ending with
For each aggregate you are likely to have all the three kinds of files because a command leads to an event, and it’s likely there are conditions under which a command cannot be handled.
We recommend gathering definition of related entity states in a file named after a business model
thing. Suppose we have a
TaskDetails projections, and
a Process Manager which is responsible for movement of a task from one project to another, there
task.proto file, with all Task-related data types definitions. A project-related data
types would be defined in a
As we wrote earlier,
ProjectId are defined in the
identifiers.proto file, and
project.proto import this file.
Data types are defined as Protobuf messages using
Identifiers are usually defined after the name of the entity with the
You’ll find such naming pattern in the API of the framework. For example,
This convention is not a requirement. We find
Id suffix short yet meaningful for building a rich
type-safe API. You may select another convention that fits your domain best. But please be informed
that future version of the framework tools will use the
Id suffix of the types and
of proto field names for code scaffolding and improving intelligence of code generation.
A command is defined as an imperative:
Events are named as facts formulated as past participles:
A rejection is named after a reason of why a command cannot be handled. It’s a fact about a state of a domain model:
Protobuf messages for entity states are defined using nouns:
Avoid using suffixes like
ProcessManager when defining a proto type,
- You may want to use such a word when creating an entity Java class which uses a generated data type for holding the state of the entity.
- Such a data structure does not represent a whole
ProcessManagerthing anyway. It’s just data.
Packages allow to form namespaces for types, avoiding clashes. It is customary to have a “root” package for an organization or a service name. Most likely, each Bounded Context would have a dedicated package.
Examples in this guide assume that a fictitious company called
Acme Corporation creates a SaaS solution.
The company has a web presence site with the domain name
The solution is a task management application called Todo List,
which will be hosted at
Packages in Protobuf do not follow the reverse Internet domain name convention, which is customary in Java. It would make sense to have a root package for all the types defined in an organization under the root package with a lowercase company name.
For the fictitious SaaS project of the Acme Corporation it would be:
Java does not have the notion of package nesting. Packages in Java are separated namespaces, which seem hierarchical for convenience. Still, when it comes to placing source code files in a project, there is usually nesting formed by the directories in a file system.
Spine framework uses this notion of “nesting” for marking multiple packages of a server-side code belonging to a Bounded Context easier. But this is a convenience feature, not a requirement.
Also there are several recommendations as to organizing generated and handcrafted code.
Have package per data type
It’s easier to see everything related to a type, if all the generated code comes under a “home” package of a data type. For example:
This package would be a part of the API shared between client- and server-side code of your application.
We recommend putting command classes under a package which ends with
The package name is singular because it reads better in a fully-qualified class name of a command message.
Similarly to commands, we recommend putting events generated by an entity under the
Similarly to events, rejections are placed under the package called
Unlike commands and events, rejection messages are generated under a file named
The class, of course, is placed into a
rejection package of the corresponding type.
The package also contains generated
Throwable top-level classes that match rejection messages.
These classes are used in the
throws clause of command handling methods.
The arrangement with message classes nested under
Rejections class, and top-level
is required to avoid name clashes while keeping these generated classes under the same package.
To avoid unwanted dependencies we find it useful to put server-side code under
a sub-package called
server, with sub-packages for corresponding entity types:
Handcrafted Java Classes
When naming entities we find it natural to start with a name of a state class and then add a suffix which tells the type of the entity:
The suffix helps when observing together with other entities in a package.
For process managers it may be enough to have the
Process suffix, dropping
which frequently worked for us too. Other options for suffixes are
It would be a good idea to decide on such a suffix as a team standard, before you start coding.
We recommend not using a type infix for naming repository classes. Alphabetical sorting would
make a repository class be next to an entity class. And you would not deal much with repository
classes anyway. So, it’s just
SomethingRepository, rather than
Names of Bounded Contexts follow
TitleCapitalization favoring plurals:
Although, singular names are perfectly fine too:
If a name of a Bounded Context is used in a package, its name is transformed according to rules of a programming language.
A Java class that creates and configures an instance of a
BoundedContext is named after the
name of the context with the