In this vein any interface that requires you instantiate all kinds of library-specific structs just to call the relevant function, and conversely upon return, is hiding the actual surface area of the interaction boundary. This makes the aforementioned asessment harder.
This can of course be a justified tradeoff for intended use cases, and this is brings me to my point: An interface author must conscientiously and deliberately adapt the interface to intended use cases.
The user, on the other hand, cannot peer into the mind of the interface author and must measure the analogous intent and purpose of a given interface in the context of his particular requirements.
A good interface, then, is one which the author has designed and documented so that prospective users
(1) accurately determine its suitability to their specific use case,
and (2) are not suprised if and when they decide to make use of it.
Changing the intended use case by exposing or hiding configurability, inverting control or establishing «sane» defaults is a red herring. It has no bearing on the goodness of the interface. Goodness comes from wether configurabiliy, inversion or defaults are apparent to the user.
Edit: spelling/phrasing
It's completely stunning to me how frequently this is forgotten in spite of having been a key component of object oriented programming when it was invented (ie smalltalk days, before I was born).
If so, what about invariants? Are invariants related to good interface design?
No. One need a specification of the intended behaviour. Behind this specification lays the interface (data type, here a Object-class). This data type on the other hand can have different representations.
Design by contract is a term i didn't read as an agreed scientific term. It is used in OO-languages for some pattern, where you "generate" (read imply) a specification. E.g. two unrelated services use the same data type within their communication. This may be injected or included within their dependencies. To me its related to code generation. It may aid the collaborations between multiple developers across multiple projects to 'move faster'. I have limited and bad experience with this.
> If so, what about invariants? Are invariants related to good interface design?
Invariants in my book are then a synonym for mixins. Which in OO-Design would be represented via dependency inversion. Invariants can be necessary at best. Its no measure for a good interface. If your data types are specified such that invariants do not missbehave, they can be used.
But don't trust me on this.
- engine has appropriate amount of oil in it
- oil filter in place
- drain plug torqued correctly
- dip stick present
- oil cap on
No matter what the outcome of the operation (ie error paths or happy path), ChangeOil promises to return with the car in a state that fulfills those conditions.
In order to do that, some preconditions need to be fulfilled too:
- car has some amount if oil in engine
- car is able to start
- no major noises
Does the car need to be checked for leaks?
At the end of filling in new oil, how much oil should be in the car? How much left over?
> The dependency (oil, in this example) is an argument, not because anyone cares to customize it, but to simplify the implementation.
This is a huge leap! I know it’s an example, but it’s perfectly reasonable to satisfy both “don’t make me bring oil to the grease monkeys” and “express oil as an explicit dependency of grease monkey activity.” It will, of course, buck some recent discussions here, but the reasonable solution to that is an additional abstraction. And it will of course not buck another long time favorite here: functional core.
1. Provide the convenience interface which defaults to some way of determining a sensible default. In the example case, bringing your own highly configurable oil to the people who change your oil is an exceedingly idiosyncratic case, but for generalization purposes let’s say that’s optional.
2. For all cases, directly provide oil to the processes explicitly dependent on oil to proceed.
+ 3. Make sure you have your dependencies: if the weirdo with super weird oil opinions supplied their own weird oil, you’re done; otherwise get your sensible defaults ready. This is super cool because,
+ 4. Now you can just put oil in the car without making the oil selection everyone’s business (responsibility).
Maybe that’s “simplify[ing] the implementation”, but not in the ways that’s usually meant. It also has the really awesome property of preventing billion dollar mistakes. This:
> Leave the argument nil, and the function will silently leave the object in a bad state.
Doesn’t have to happen, even if your language/environment is predisposed to it. For the cost of a fairly mundane function boundary, you get a convenient interface for users who don’t care about how the oil sausage is made, and free null safety.
> What the caller probably wanted was more like this
I really don’t think that’s a reasonable assumption at all. What the caller probably wanted was more like this:
func ChangeOil(c Car, oilType OilType) error {
// There, that’s the whole function body
}
“be conservative in what you do, be liberal in what you accept from others"
func GetOil(oilType OilType) Oil {
...
}
func ChangeOil(c Car, oil Oil) error {
...
}Ah, well, maybe I missed the point entirely.
It’s not even a terrible pattern if you’ve already accepted shared dependencies as a thing (which you have to do in reality), but it’s much easier to reason about if you isolate them to something that provides explicit dependencies where your logic happens.
Font is Inconsolata (https://fonts.google.com/specimen/Inconsolata)
public ResultType ChangeOil(Car c, Oil oil = null); is enough.
In the actual implementation of the interface we can check if oil is null and if it is, provide own oil which fits car. If oil is not null, we can check if it is enough and if the type fits car type.
We also can return a car with changed oil and an error.
However the user of the interface shouldn't be concerned with actual implementation details. The same way an user of a Web API shouldn't be concerned with actual implementation detail.
And then, when some poor programmer finally comes to writing an actual implementation, he finds out that it's literally impossible without magic.
Example codes:
And ChangeOil(car, nil) makes complete sense to remove all the car’s oil: in Go, a nil slice is (essentially) equivalent to [].
I argue that the "better way" has more conceptual overhead. if this was a large project. just changing oil would require to understand many ideas.