Bob Martin raises a good example in InformIT: Robert C. Martin’s Clean Code Tip of the Week #1: An Accidental Doppelgänger in Ruby > Duplication of two functions that do the same thing but mean different things by it.
I recently stumbled into a slightly different take on the question of should a function say what it does or what it intends?
When a function implements business process Alpha that today consists of steps A and B (but tomorrow may change) should you call the function DoBusinessProcessAlpha or call it DoStepsAandB?
One answer would be, if the function is in a public package which exposes business functionality then the name should probably show that it does BusinessProcessAlpha. But if it is a private, not exposed, function then the reader is probably looking for the detail, that it does StepsAandB.
The question is more awkward if Steps A and B are themselves business process functions. That is, if you asked your customer, they would understand what steps A and B mean.
I suppose in that case you could always call it DoAlphaAsStepsAandB().
It’s an interesting take, but if Business Process Alpha changes to also include step C, or to remove Step B, not only do you have to modify the contents of the StepsAandB method, but you also have to rename it and update all the calling sites to use the new name.
The fact that process Alpha consists of specific named steps is an implementation detail of the DoProcessAlpha method and not the business of any callers of that method. A caller which needs Steps A and B, so it calls DoProcessAlpha as a convenience to get both at once, is violating encapsulation. DoProcessAlpha is a method reserved for callers which need to execute process Alpha, whatever steps it may contain. Anybody who needs to interact with the individual steps outside of an Alpha context need to make a new method to call those steps directly.
Darn it, I need to “like” this reply. Where is that button?
One day, I’ll check the WordPress plugin options for like buttons
I think the challenge I want to put back to you is : Does “implementation detail” mean “technical software detail meaningless to the business” or does it mean “Business decision about how this company does Process Alpha.” The interesting case is the second one.
If A,B,C are technical software details, meaningless at the business level, I would go with your analysis based on encapsulation. But if they name parts of the Business Domain, then they should not be encapsulated. That would be the equivalent of telling the boss, “yes we do process Alpha but I’m not telling you how we do it.”
If Steps A and B are business decisions about how we do Process Alpha, then I want that business decision – that requirement– to be visibly reflected in the code.
If the business customer says next week, “We’ve decided to change how we do Process Alpha. We are going to do it with Step C and D instead of A and B”, then I say to them, fine, we’ll change it to do that. They understand that there is a cost, I make changes and end up with ProcessAlphaAsStepsCandD.
It matters that the code reflects the business decision – the requirement – that we now do process Alpha by doing C and D, instead of doing A and B. That’s not an implementation detail, it’s a customer decision.