2 ms·
You need well-defined interfaces to be able to reason meaningfully about the interactions. That usually requires comprehensive documentation, and for the implem
by layer8 5y ago
You need well-defined interfaces to be able to reason meaningfully about the interactions. That usually requires comprehensive documentation, and for the implementations behind those interfaces to actually stick to the documented interface contracts.
A sibling subthread notes that it has become more of an experimental science than a mathematical science. That is getting at the heart of the matter. You lose the ability to reason about the interfaces; instead you have to poke a stick at them and see how they react, and build an incomplete and often inconsistent mental model based on that, instead of being able to rely on the interface and its documentation to provide you with a comprehensive mental model that is all you need to reason about and predict their behavior.
- drewcoo 5y agoWell-defined and well-documented are usually orthogonal properties. You hit the nail on the head with mention of contracts. We need wider adoption of tooling like Pact. (Ironic link to Pact docs follows.) https://docs.pact.io https://docs.pact.io
- layer8 5y agoWell, if it’s well-defined but not documented, then you can’t tell the definition and can’t judge wether it is well-defined. If it’s documented but not well-defined, then that means that the documentation is incomplete (there is “undefined” behavior) and/or inconsistent. Having a complete and consistent definition (which is what I would call “well-defined”) is almost the same as having a complete (describes all behaviors) and correct (the actual behaviors match the documented behaviors) documentation.