Saturday, October 21, 2017

Simple and precise problem definition leads to the best software specifications

Simple means "easily understood or done; presenting no difficulty". Precise means "clearly expressed or delineated".

See the below simple specification:
"Examine any workflow task with status 'not started' and send a 'tasks pending to be performed' notification to its owner if for such task workflow there is no previous task or if the previous task is in status 'completed'"
It is easy to understand and there should be no difficulty involved in its implementation. However this specification is not precise, and because of it the transaction costs will make its implementation at least an order of magnitude more expensive than its counterpart simple and precise specification:
Create task owner 1
Create task owner 2
Create workflow 1 with two tasks in 'not started' status and no owner
Create workflow 2 with two tasks in 'not started' status and no owner
# Make sure the owner is not a mandatory field and that there is a default status:
Upon submission confirm these tasks persist and their status is 'Not Started' 
Add owner 1 to workflow 1 task 1
Add owner 2 to workflow 1 task 2
Add owner 1 to workflow 2 task 1
Add owner 2 to workflow 2 task 2
Upon submission confirm that owner 1 gets two 'tasks pending to be performed' notifications 
Set status 'In Progress' for workflow 1 task 1 # Note we introduce another possible status
Set status 'In Progress' for workflow 2 task 1
Upon submission confirm that no 'tasks pending to be performed' notifications are sent
Set status 'Not Started' for workflow 1 task 1
Set status 'Completed' for workflow 2 task 1
Upon submission confirm that owner 1 gets one 'tasks pending to be performed' notification for workflow 1 task 1 and that owner 2 gets one 'tasks pending to be performed' notification for workflow 2 task 2
Instead of going through the above top-down exercise that would allow to put automated end to end (e2e) testing in place and guarantee that important business rules are never broken we go lazy both with specs and QA. Documentation and QA are as important as implementing the functionality for your product. The three of them should be simple and precise. In this post I am explaining how the documentation problem is resolved. I should probably write about how to resolve the implementation and QA problems soon ...

No comments:

Followers