4 ms·
I think the emphasis on the documentation is a bit of a red herring. Sure, documentation for most things could definitely be better. But when you are building a
by conjecTech 4y ago
I think the emphasis on the documentation is a bit of a red herring. Sure, documentation for most things could definitely be better. But when you are building a system that is a composition of subcomponents, the bulk of the complexity is almost always going to come from the interactions. Those aren't things that can be readily captured in the documentation of any single component.
This conclusion is actually pretty obvious when you consider it from a testing/dimensionality perspective. If you have 2 components with N inputs, an interesting application using both may have close to 2N inputs. Sounds pretty tame, but the size of the space grows _exponentially_ with dimension. And for a bounded space, almost all of the volume will be near the surface, which would mostly correspond to non-trivial combinations of the inputs. I think we tend to lump most of the code needed for this complexity into "business logic".
- pc86 4y agoThe system should have its own documentation though. It's fine if that documentation is basically just explaining all the interactions (especially if that's the bulk of your system). But that doesn't mean the individual components shouldn't have good documentation.
- saiya-jin 4y agoAh, the variant of classic 'code documents itself'. Which is true unless you come to a dark place where stuff stops working randomly and you have no clue why. Or you interact with other systems which are just blackboxes for you. Its fairly trivial to write on few lines piece of (bad) code that is really hard to grok for anybody else and even for you after few months / years. What good documentation does, and it can take just few lines here and there, is explain why things are supposed to happen or not, expectations, corner cases etc. Haven't heard any good argument against that in past 20 years and doing this myself diligently even on code that is purely for me. Always thanking myself when debugging something old.
- conjecTech 4y agoI didn't mean to diminish the value of documentation. It's hugely valuable. My point was that even if the documentation for all systems was good, the bulk of work in a mature software environment would still be integration, since that's where most of the complexity emerges.
- layer8 4y agoYou 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 4y 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 4y 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.