About 6 months ago my team wrote an app that allows a user to change aspects of their order.
The app works by first initiating a transaction and then guides the user through a series of steps until a "review changes" page is reached. On the review page the user can review their changes and either submit, repeat the flow and make further changes or cancel.
Between each step in the flow an api call, updateOrder, is made to save progress. However when moving from the last page in the flow to the review page a different api call, updateOrderWithPrice, needs to be made, which, in addition to saving their changes also recalculates the price of the order to be presented on the review page.
The api call updateOrderWithPrice takes longer than updateOrder because in addition to saving the changes to the transaction it has to also calculate the new price.
Everything works well, except that the decision of when to use updateOrder or updateOrderWithPrice is left up to the developer and therefore the developer has to be familiar with the api. This is particularly a problem when onboarding new developers and I have seen the wrong api being used.
We know that the updateOrderWithPrice api is synonymous with moving from the last page in the flow to the review page. likewise, updateOrder is synonymous with moving between the earlier pages in the flow.
Therefore to reduce the cognitive load and human error we should remove the choice from the developer and instead have an underlying mechanism in the application that makes to decision for the developer. Therefore the developer only needs to specify which page to move to next and the application will decide whether it needs to call updateOrder or updateOrderWithPrice. This removes the burden from the developer and therefore the chance for human error.
There are many ways this could be done and it would depend on the application. This particular application uses React Redux so we can therefore take advantage of this by introducing a middleware that persists calls the appropriate api when the the action to move to the next page is dispatched.
To me this is the difference between smart code and dumb code. Dumb code simply executes what it's told to and leaves all of the decisions up to the developer. Smart code by contrast is goal focused and takes care of the underlying details of achieving that goal. In the case above, the developers goal is the move to the next page and only needs to decide which page that is, the rest is left up to the application.
This would also simplify testing as you would initially have a test to prove that we moving between pages the right api is called. The when creating a new flow you would only need to test that the user is navigated to the right page, not which api is called since that test already exists.
Top comments (0)