The “Who_Does_What” choice naming convention conveys the business purpose more clearly
It is generally advised in he Daml community to prefix choice names with the template name.
This convention, from a technical perspective, has its own merits, most importantly it makes avoiding duplicate choice names easy.
From a business perspective, though, a choice implements a “who does what” decision. Why not reflect this purpose in the choice naming convention?
One of the most unique features of Daml is that we handle real-life actors within the code. A ledger party in the Daml code implements the restriction, that on a working ledger, only those real-life actors can exercise the choices dedicated to that ledger party who attach a valid access token to the API call containing that ledger party in the “actAs” field of the token.
Understanding the relationship between ledger parties and choices is one of the most important things for business process experts and UI developers.
When a Daml developer looks at the template code, for her, it’s obvious which ledger party is the controller of the choice because it’s written there.
But business stakeholders and UI developers encounter choice names usually in contexts where the choice controllers aren’t specified explicitly.
From a business perspective, a choice implements a “who does what” decision. Why not reflect this purpose in the choice naming convention?
Understanding the relationship between ledger parties and choices is one of the most important things for business process experts and UI developers, who encounter choice names usually in contexts where the choice controllers aren’t specified.
This is the case e.g. in the Navigator UI, where all the choices are displayed with a contract, irrespective of wether the party logged in can exercise them or not.
Another case is the visualization of a template package, where only the choice names are displayed.
Let’s look at an example, the delegation pattern.
The description of the pattern can be seen in the documentation here, the full code sample is contained on Github as part of the Daml code base here.
The coinPoA contract makes it possible for a principal ledger party to delegate the right of exercising the Transferchoice on a Coincontract to an attorney ledger party.
From this code snippet it’s clear that the the principal ledger party can withdraw the delegation by exercising the WithdrawPoA choice, and the attorney ledger party can initiate the coin transfer by exercising the TransferCoin choice.
But if you are a business stakeholder or a UI developer, you might not look at this code. You might look at e.g. the visualization of the template package.
The graph representation of the whole package is quite big, because it covers all the interconnected templates:
Within the graph of the whole package, this is the representation of the CoinPoA template:
On this representation you can see that the attorney and the principal party is contained in the contract payload, but you cannot tell which party can exercise which choice, without looking at the Daml code.
If you, on the other hand, prefix the choice name with the choice controllers, this relationship becomes apparent:
This naming convention also helps to tell on the Navigator UI wether the logged in party can exercise a certain choice or not.
