Ok, lets see now hot all these is relates with software development. Lets start with a couple of questions:
- Have you already, debugged an API or any software unit in order to realise what it does?
- Have you spend hours using the approach "try and fail" to be sure about the side effects of a design change?
- Have you looked to a method/function/procedure that returns nothing, receives no parameters and throws meaningless exception?
- New people joining on the team.
- Lack of tests
- No "useful" documentation.
What means be Explicit?
First of all, lets look for a definition of the word explicit:
- Fully and clearly expressed; leaving nothing implied. Meaningful
- stated clearly and in detail, leaving no room for confusion or doubt. Fully Understanding.
- Fully and clearly defined or formulated: "generalizations that are powerful, precise, and explicit" (Frederick Turner)
How to get there?Here are some tips I use to make my designs more explicit:
- Look for deep understanding on the domain - This a a pre-requisite to all items that are gonna follow. In order to find out the right abstractions, you need to understand the rules, see the entities, recognise its behaviour, the boundaries, etc. Everything starts from here. If you don't find the right abstractions, something will be missing in your design and the chances to achieve explicit will be smaller. This knowledge usually comes with time but as soon you get there, the explicit we are talking about Will emerge.
- Minimise the side effects - side effects are hard to make explicit. When trying to make them explicit we usually end up with a complicated and unclear solution (i.e, checked exceptions, sharing state). On the other hand, hide it totally sounds unnatural couse it will hard to predict them when using the system. If you can't get right of them, try to minimise shared state internally and use other software design techniques to deal with failures on the right place.
- Create meaningful interfaces - In the end of the day, we expose APIs and functionalities through interfaces. Interfaces need to be clear enough about what they are suppose to do when used. It pass through finding the right abstractions giving to it the right names.
Be explicit is a matter of being honest about what are the intentions (Intention reve of your design. It is It does not mean an implementation should reveal all its internal details but instead, providing the necessary information to the that are interested use it safely, without misunderstanding.