emanuelpalm
commented
3 years ago These Names Need Not be Bound by Programming History
Among programmers, it is customary to stick to a subset of the ASCII character set ([A-Za-z_][0-9A-Za-z_]*) when naming artifacts. The reason for this is historical, as many programming languages have decided to stick to the limitations imposed by early programming languages and character sets. I want to propose, however, that the naming of systems, services, service functions and service function types are not bound by this convention, but are instead encouraged to use a form closer to regular English, which means that spaces, colons and commas may be used in these names (even I don't really see any reason why the two latter ever would be relevant).
In other words, these names would be preferred (especially in documentation):
Certificate Authorizer, Device Registrar, Event Publisher.
While these forms of the same names would be advised against (but may, of course, be used in computer code, configuration files or wherever it would be required by the programming language or context in general):
CertificateAuthorizer, DeviceRegistrar, EventPublisher.
jerkerdelsing
jenseliasson
vanDeventer
Note that this is not the same as the naming convention established in (Paniagua, 2019). This is about how to come up with names, not with how to structure and spread them via DNS-SD.
As a programmer, I have been taught that consistency in naming is a boon to productivity. If you have a systematic way to name your artifacts, you will instantly know what types they have when you see their names. I wish Eclipse Arrowhead would have the same.
I propose the following:
System Names
Description: A system can be seen as something capable of fulfilling a role. As a consequence, I believe systems should always have agent nouns as names. An agent noun is the agent or title form of a verb. In English, such nouns typically end with "-or", "-ar", "-er" or "-ist". The verb indicates what the system does when fulfilling its role. It being in its agent noun form means that you are referring to the doer rather than the action itself. Examples: Service Registrar, Authorizer, Orchestrator, Gatekeeper, On-Boarder, and Certificate Authorizer. Exceptions: The current Gateway system is kind of an odd bird, as it does not provide any regular services at all (if not counting the echo and management services). As it can only function in tandem with a Gatekeeper system, I don't really mind it keep being called Gateway. The word Gateway gives it an obvious connection to the Gatekeeper system, which I also like.
Service Names
Description: A service represents a certain task a system is capable of performing. I believe services should have verbal nouns, or other nouns with derivable verbs, as names. Agent nouns are, of course, off limits, even though they qualify as deverbal nouns. The name is a noun to indicate that it can be performed rather than it being performed. The name being related to a verb means that it becomes more apparent what is happening when the service is invoked. Suitable endings of such verbal nouns could be "-ment", "-ing", "-y" or "-ion". Examples: Service Discovery, Authorization, Orchestration, Gatekeeping, On-Boarding, and Authorization Management.
Algorithm NamesOperation NamesDescription: A service
algorithmoperation represents a certain action a system is capable of performing as part of it fulfilling the task associated with one of its services. I believe algorithm names should be in the imperative mood, which means that they take the form of commandments. This is customary for naming functions in most programming languages. Examples: Authorize, On-Board, Register, Discover, Lookup and Qualify. Exceptions: This does not mean that RESTful service implementations should have endpoints likePOST /authorize. The SDs should have the imperative mood names, while the corresponding RESTful IDDs should stick to the REST convention and use enpoints likePOST /authorizations(which adds anotherauthorizationobject to an imagined folder of authorizations).Type Names
Description: A type names some kind of message, or structure or primitive that can be part of a message sent to or returned by a service function. Following regular programming convention, these should have names being proper nouns, optionally with preceding adjectives. Examples: Authorization Request, On-Boarding Request, Service Record, and Orchestration Record.
Words With Specific Arrowhead Definitions
It is typically wise to avoid using names that can become ambiguous in system contexts. Examples of such names are "Manager", "Handler" and "Data". The reason for this is that all systems manage data, and handling is synonymous with managing. What does a Data Manager really manage? It is not very obvious from the name, as all computers manage data. How exactly does an Event Handler handle events?
However, as Arrowhead is a new thing, we are free to give general words such as these very specific meanings. For example, it is already the case that the word "Management" in a service name indicates that the service is meant to allow for the administration and configuration of the system in question. Why not formalize it? @jenseliasson Could you think of a similarly precise definition for the word "Handler"?