Comment by torginus
3 days ago
I think it's an important property of a system to be documentable not just documented. What I mean essentially, is the system was designed with sound principles, and said principles were written down and followed.
I have seen this work only once in my life, and it was so nice to see, but yeah, most code is just a ball of twine, and even if there was a guiding principle beneath, it has been long abandoned, and overruled, and the only way to understand the system is to take it all in at once.
I think it’s reasonably easy to design a system that’s documentable and documented. It’s very, very hard to maintain and iterate on a system while maintaining those properties.
Hacky things will make their way in because it takes a month to do the documentable thing and a week to ship the hacky thing.
It takes a lot of skilled people from varying disciplines to figure out what things are going to survive long enough and be important enough to spend the resources doing the right thing instead of the hacks.
It bites both ways. I’ve seen core business products crippled by years of digital duct tape, but I’ve also seen internal tooling that never really becomes useful because they insist on doing the “correct” thing and it’s constantly a year behind what we need it to do.
Let me give you and example of what I referred to - I used to work on a big enterprise app that was a desktop app, it had a dockable very complex user interface and a quite sophisticated data management layer that you were supposed to integrate with to display and query stuff.
These core services were extremely well designed and documented, and if you wrote a component using them, you could be reasonably certain the UI displayed correctly, behaved consistently etc.
But imo even more importantly, due to the patterns these components enforced, if you wrote a component like this, chances were somebody could go in and read your code and understand what it did, and if you depended on external stuff, even then it was very clear on what and how.
A lot of the code was using this correctly, but some wasn't for whatever reason. And the ones that didn't were utter hell to work with, as they could change state any time, did things their own way, depended on implementation details etc..
Essentially had to understand the whole code base, like what services call where, in what order to things happen etc. to work with that code.
Behavior of those components was essentially 'what the code did' and therefore undocumentable.
For reasons, the amount of code belonging in the latter category grew and grew, and eventually it infected the core systems, as the invariants described by the documentation basically no longer be expected to hold in any scenario, and the whole thing became an undocumentable ball of twine, where the code did things not because it made sense, but to work around bits and quirks of other pieces of code.