What I find interesting is that most of this discussion about being explicit is about explicit actions/implementation details. I find being explicit very important but I look at it from different perspective.
When I search for the meaning of explicit I get the following:
stated clearly and in detail, leaving no room for confusion or doubt.
To me it’s all about being explicit about the meaning of the code. The part leaving no room for confusion or doubt is very important. This ties in to “don’t surprise me”. What the code says it will do, and what it actually does when you call it, should match. And it only should use the appropriate actions to get to that outcome. No surprises. How much detail you need depends on the context.
I would say this:
stated clearly and with enough detail as to leave no room for confusion or doubt about the outcome in the current context.
Here’s a simple javascript example
if (person.sex === 1 and person.children.length > 0) { ...do something... }
From a technical standpoint this is very explicit. I know what it’s checking. But I have no clue what the meaning is from a business logic point of view.
if (person.isFemale() and person.hasChildren()) { ...do something... }
This looks much better but it might only have made it more readable. What if this code is specifically about female parents. Is this clear from the if statement? You can assume it’s correct but maybe someone forgot a check. There’s still room for doubt.
if (person.isFemaleParent()) { ...do something... }
To me this code is very explicit, yet it hides the details. It tells you exactly what the code cares about from a business perspective. There could be a bug in isFemaleParent but you know precisely what it’s supposed to check and there’s no confusion or doubt about the meaning.
In case of an API, be explicit about what it returns or what the outcome is. This can be an API contract. The consumer still wants you to be explicit, just about the outcome/result, not the implementation details. For example, with a GraphQL API you’re being explicit about what the consumer can ask for.
So I agree with your opinion about hiding complexity. I just believe being explicit should focus on the meaning/outcome of the code (in context), not the actual implementation details.
