Recently I was having some discussions on the naming of Service-Oriented Architecture (SOA) services and their operations. There were some differing opinions on the length of the names and concerns about the duplication of some words in both the service name and operation names.

Naming Principles

As a general set of principles, I prefer to use names that are: intuitive, understandable, more readable in typical English, discoverable and allow for extensibility.

Microsoft has some useful naming conventions and guidelines for .NET that are reasonably mature and generally can be applied to SOA service names.

• General Naming Conventions
• Abbreviations
• Class Naming Guidelines

Service Names

As an example, let us assume that in a domain we have products/stock/inventory that is acquired and sold. We could say that there should be a service for the management of inventory items.

We therefore could propose an “Inventory Management” service to record the addition and removal of stock. A valid alternative name also could be “Inventory” service. “Inventory” as a service name obviously is shorter than “Inventory Management”. So is that better?

One could at this point perhaps flip a coin and naively settle on either option. But I wouldn’t recommend that…

Do those service names comply with the above-stated principles? Maybe - it depends on the domain.

Let me now give you some more possible information about the domain. When inventory is sold or moved to another department, there are typically corresponding accounting entries that need to be recorded. We therefore could propose an “Inventory Movement” service to encapsulate this.

So now in this domain, we optionally could have the following:

1. “Inventory” and “Inventory Movement” services, or
2. “Inventory Management” and “Inventory Movement” services.

For me, seeing the juxtaposition of both service names in option (1) makes me feel uneasy, highlights ambiguity and causes me confusion. Since there is “Inventory Movement”, what is the role of “Inventory”?

Additionally, “Inventory” sounds very much like a data entity that one might perform CRUD operations on - as opposed to a Business Service.

Option (2) however is more intuitive, less ambiguous and causes me less confusion. “Inventory Management” intuitively sounds like it could be related to the management of inventory items (whatever that may be…). Overall for me, this makes more common sense than option (1).

So now, if you agree, we can see that the more specific service name of “Inventory Management” (even though it is longer and slightly more annoying to repeatedly type) better allows for business changes within a domain. In other words, more specific service names allow for future extensibility of the domain with less ambiguity. Having said this, we do need to remain vigilant and be careful that we are not overtly specific with our service names such that we make our services to narrowly focused…

Ok, let’s now look at the operation names.

Operation Names

As an example, let us assume that we have an “Order Management” service. In this service we need to have operations for adding new orders to the system. We might therefore have an operation named “Add Order”. Alternatively, we could have an operation just named “Add”. “Add” is obviously shorter than “Add Order”, and does not repeat the word “Order” - which you know from the service name. So is that better?

One could at this point perhaps flip a coin and naively settle on either option. But I wouldn’t recommend that…

Do those operation names comply with the above-stated principles? Maybe - it depends on the service.

Let me now give you some more possible information about the service. Existing orders may need to be adjusted. In fact, there might be a need to add new order items to an existing order. We therefore could propose another operation named “Add Order Item” or “Add Item”.

So now in this service, we optionally could have the following:

1. “Add” and “Add Item” operations, or
2. “Add Order” and “Add Order Item” operations.

Again, for me, seeing the juxtaposition of both operations names in option (1) makes me feel uneasy, highlights ambiguity and causes me confusion. Since there is “Add Item”, what does the operation “Add” actually add?

Option (2) however is more intuitive, less ambiguous and causes me less confusion. Overall for me, this makes more common sense than option (1), and provides extensibility to allow for other operations in the future with less ambiguity.

Summary

I recommend erring on the safe side and selecting names that remain intuitive when taken out of the context of its grouping/category, and be carefully explicit with names - because you don’t know how the business is going to change and how that could affect the domain. This is especially true if your team is operating in an agile fashion and developing and evolving the services and operations as you go.

The length of names and duplication of words in operation and service names should be less of a concern than using names that are intuitive and allow for change with less ambiguity. If you are not explicit enough, then you increase the risk of future services or operations making your existing names ambiguous. Alternatively, if you are too explicit, you could narrow the scope too much and reduce extensibility in other ways.