Message Naming Guidelines

Sponsor: Do you build complex software systems? See how NServiceBus makes it easier to design, build, and manage software systems that use message queues to achieve loose coupling. Get started for free.

As with many things in software development, naming can be difficult. The name of a message can be incredibly important which is why naming of your messages should be taken with consideration. This post is to be used for message naming guidelines with dos and don’ts based on my prior experiences of the good, the bad, and the ugly.

This blog post is in a series related to messaging. You can find the overview in my Message Properties post.

YouTube

If you haven’t already, check out my YouTube channel where I’m covering this blog post in video form.

Commands vs Events

Commands and Events are the types of messages I generally deal with within a system. We need to differentiate between commands and events because they will be named differently depending on which one they are.

Commands

Commands are messages with the intent to change the state of the system. They are actions to be performed that have side effects. They may be created by an end-user or another part of the system that could be automated. They are a way to execute behavior.

I try to avoid using Create, Update, Delete, Save prefix as the verb. Rather I try to focus on the business process and the intent of the user to initiate the state transition. This can be one of the verbs mentioned above, but try and dig deeper to reveal the actual intent.

My general guideline for naming is a verb and a noun. Basically the action against a thing.

Do

PlaceOrder
GenerateInvoice
ApplyDiscount

Don’t

Order
SaveInvoice
Discount

Events

Events are statements of fact. They are named in the past tense. They are named this way because they have already occurred. Events are things that have happened within a system. They are the result (not in method return sense) of an executed command.

I try to avoid Created, Updated, Deleted suffix as the verb. Trying to stay way from CRUD naming to get to the essence of what actually occurred from a business process view.

My general guideline for naming an event is a noun and a verb. As mentioned the verbs are past tense.

Do

OrderPlaced
OrderInvoiced
DiscountApplied

Don’t

Ordered
InvoiceCreated
Discounted

Suffix

I generally prefer using a suffix of Command or Event to your types/classes. Ultimately, my only guideline is to be consistent in doing so. If you choose to suffix, always do it, if not, don’t ever do it. Consistency is key.

Examples

PlaceOrder vs PlaceOrderCommand

OrderPlaced vs OrderPlacedEvent

Serialization

If you are persisting events to an event store, document store, or relational database, you’re likely serializing your event objects.

Consumers of those events will then pull those serialized event objects out of the store and try and deserialize them back to an event object you want it to be in the original type.

For example, in .NET you might be serializing using JSON.NET;

The issue now is how do you deserialize this string back to an OrderPlaced type?

Don’t

The first reaction may be to include the CLR Type name alongside the JSON. You can accomplish this by using the TypeNameHandling setting the serializing:

This would result in a $type property that points to the CLR type. When deserializing this string, you can now get it back as the original type.

I discourage using the explicit CLR type information alongside the event because you are very likely going to either rename, change the namespace, or assembly of an event. And at this point, you won’t be able to deserialize using this information.

Do

Include and persist a separate piece of static data alongside your serialized event to define what the name of the event is. This should be concrete and manually mapped from this string to a specific type you want to deserialize to. This allows you to move the specific event type to any assembly, namespace or even rename.

You can see an example of this in my SQLStreamStore demo/sample application.