Would it be OK if I mention actor in the command/query name when I use CQS pattern

Question

I'm applying Clean Architecture + DDD (maybe) in my project (web Application + REST API).

The good thing I learned from the Clean Architecture is using "Interactors" to show business use cases in my code, which is naturally fit with Command pattern. So that I use Command Patterns in my project.

Normally, I named my command as "AddNewRequestCommand".

But I'm thinking about change it to "AgentAddNewRequestCommand", which naturally fit my user story and the command itself show the full context of the command because every use-case need an actor.

Say I have this User Stories:

1. As an agent I want to add new delivery request, so that I can deliver my goods.
2. As an agent I want to list my created request, so that I can manage my created requests.
3. As an administrator I want to list all request in the system, so that I can do the customer support easier

Will result:

1. AgentAddNewRequestCommand
2. AgentListCreatedRequestQuery
3. AdministratorListAllCreatedRequestQuery

(Agent,Administrator..are business actors, It's not about roles/permissions)

Good:

• Commands/Queries will show all user story of application
• Command/Query show actor & context of the use case. So that I can get a bigger picture of the use case. I don’t have to ask a question like: “Who will execute this command”
• Convert User stories to Command/Query easily. So that, developer & BA/PM can say the same language.

Bad:

• It will cause some confusing between Actors and Roles: How about I’m an administrator & I want to add new request.

What do you think?

Answer 1

Naming

Can we please stop naming things badly?

Just because something is an implementation of a "Command" pattern, does not mean you should add "Command" to it. "AddNewRequest" is a command. You can tell because it is phrased as an imperative, a Command in the English Language. A "CommandCommand" is superfluously stating the obvious, and is perhaps a little patronising to your fellow developers.

Similarly adding "Agent" because it is used by an agent is not terribly helpful, and quite probably misleading. Why, because where ever "AddNewRequest" is used, Are that commands users. If you try to stipulate the user, you will get into weird situations where you are using an "AgentCommand" in tests, in an Agent, in the Console, from another Command, etc... So is that Command using "AgentCommand" wrong because its not an Agent?

Similarly why:

• AgentListCreatedRequestQuery
• AdministratorListAllCreatedRequestQuery

when:

• ListRequests
• ListAllRequests

are arguably better.

If you wish to quibble about "Request" being confusable with a "HTTP Request" then draw from your domain:

• ListDeliveryRequests
• ListAllDeliveryRequests

Also unless there is an overwhelming reason to have two separate search functions lets just collapse them down. Mostly because as with the "Agent" example, they should not be trying to dictate who the user is - and they happen to be identical at a technical level.

I am a user, I wish to list the Delivery Requests that are in some state, so that I can use that information.

Regardless of if I have administrative privileges, or privileges to one set of customer data this Command returns only those Requests that I asked for, and are permitted to see.

So:

• ListDeliveryRequests

Mapping User Stories to Code

Please avoid one to one mappings. It makes for brittle code, and poor design.

These stories are not code. They are only a way for the customer to try and express what they want the software to do to you. Past that they are useless. The software becomes the definition.

For context imagine that tomorrow the client says that both Agents and Administrator need to be able to get requests sorted by date.

If you implemented with a one to one mapping, you are doing double the work, have double code, double the bugs, and when you fix a bug for one group and forget to update it elsewhere double the reputation loss.

If you implemented the functionality more efficiently by understanding the underlying intent, you can reduce the work load, reduce the amount of code, reduce the number of bugs, and know that when the bug is fixed, it is not haunting you elsewhere.

Authorisation

Passing the user information into your commands makes good sense, otherwise how will the new Request be associated correctly with the user, and how will the search retrieve only Requests that the user can see?

Answer 2

I wouldn't recommend doing this, as it complicates command class names and can blur their intent.

Having a UserId field in your commands is, however, a good idea.