HackerWhat does a module promise its callers?
Try replacing a module whose callers rely on its incidental return order. Start with what the interface says, then trace the decisions it hides and the behaviors people have learned to expect.
Questions in this reading · 7
- Which choices should an API leave out?
- How much can a small interface hide?
- Small objects or small interfaces?
- When does a module boundary freeze a decision?
- When does an implementation detail become a promise?
- When does an implementation detail become a promise?
- Can two versions coexist under the same name?
Which choices should an API leave out?
Removing an uncertain feature reduces what clients must learn. Separating tangled concerns reduces how many choices they must consider together.
Compare original passages and timestamps · 2
When it doubt, leave it out.start seeing interconnections between things that could be independentHow much can a small interface hide?
A small API reduces the concepts callers must learn. A deep module makes that small surface useful by hiding substantial implementation behind it.
Compare original passages and timestamps · 2
When it doubt, leave it out.very simple interface with a very large amount of functionality underneath itSmall objects or small interfaces?
One talk breaks code into smaller responsibilities. The other limits what callers must learn. Count the decisions exposed to callers as well as the objects inside the implementation.
Compare original passages and timestamps · 2
make smaller thingsWhen it doubt, leave it out.When does a module boundary freeze a decision?
An interface can shelter callers from a changing implementation. Once clients depend on its behavior, changing the interface itself becomes more expensive.
Compare original passages and timestamps · 2
the higher the cost of communication the less iteration will happen therenot be able to take it out once you put it into an API.When does an implementation detail become a promise?
Callers can depend on observable behavior that was never documented. Changing an interpreter or a library then becomes a compatibility decision.
Compare original passages and timestamps · 2
people actually depend in very bizarre ways on some of the internalsanything a user can observe about the implementation of your APIWhen does an implementation detail become a promise?
Interpreter behavior, hash tables and public APIs illustrate how callers come to rely on what they can observe. Observable behavior need not have been formally guaranteed.
Compare original passages and timestamps · 3
people actually depend in very bizarre ways on some of the internalsthey will rely upon
it, given enough users.not be able to take it out once you put it into an API.Can two versions coexist under the same name?
A module name can force a choice between versions. Identifying content by its hash gives each version a separate address.
Compare original passages and timestamps · 2
we would have to make S modules also have a version identifierthen it would be perfectly fine to allow as many different versions of the same library in our code baseTry it on your own example
For an interface you plan to change, which behaviors are guaranteed and which have merely stayed the same?