4 ms·
I have this law that I call "Chesterton's Documentation". If the reason for the fence isn't documented, do not be shocked when someone inevitably comes and deci
by deathanatos 4y ago
I have this law that I call "Chesterton's Documentation". If the reason for the fence isn't documented, do not be shocked when someone inevitably comes and decides to remove the fence. If you want your fence to stick around: document the rationale. That way, later people know if the reasoning still holds. And if you're at the point where the fence is being removed: might as well bite the bullet. The way I see it, the fallout from the removal (if there is to be any) was sealed at the moment it wasn't documented.
I've come across so many of these in my career. It's not even a rare occurrence (and the author gets this, "And just like that, we are again at step 1 of our debugging journey.") While in the author's case there was a reason for the fence to exist, IME quite often there just isn't. But I've also spent a lot of time working at startups where the mentality was "move fast and clean nothing up".
Sometimes, ^F the thing you're interested in Slack. I've solved a number of code archeology mysteries with that. (But, I doubt it would help here. The author's problem lacks enough context / good search terms. It works better when you have something with a solid name, like a VM.)
- ProZsolt 4y ago> The way I see it, the fallout from the removal (if there is to be any) was sealed at the moment it wasn't documented. But the person who removes it have to deal with the aftermath. Midnight callout, fixing corrupted data, etc.
- deathanatos 4y agoSure. You don't blindly remove stuff, you do investigate and try to rule out as many possibilities as possible before clicking the "nuke" button. I.e., you manage the risk. The alternative — following Chesterton's parable absolutely — means you'll be dragging along, and critically, paying for — both in cash and in complexity of understanding —, an ever-accumulating Katamari of junk that, in all probability, serves no purpose whatsoever. Trying to justify "we want to continue to paying indefinitely for this thing that we don't thing does anything important, but we're not at all sure" — well, at the very least, you're going to look like a clown if you try to pass that by any sort of management that's not asleep at the wheel. I've removed an awful lot of this stuff in my career. I've gotten remarkably good at deleting a lot of infra with minimal to no impact. Mostly, that comes from first knowing how the actually important infra works, which helps rule out that the odd end over here is going to have any impact at all. Occam's razor helps greatly: asking, "if it did have an impact, how?". Graceful decoms, such as imaging a VM, or just stopping it for a month prior to out-right deletion, again help build confidence in the non-impact, and reduce the risk if you're wrong: you just turn that VM back on. I.e., having a rollback plan such that if there is some unforeseen contingency, that you can get back to the original state. (Though every now and then, there is an odd service for which you can't do this. Those are annoying.) But even a rollback is good: it provides a valuable clue as to what the unknown thing does, and now you know where to start digging. It's one of those things where the pragmatic view is the middle ground: wildly deleting things is a poor choice, but so too is blindly keeping things. Particularly when corps these days want to retain nobody past ~2 years, you end up with a lot of knowledge getting bus factored. If you don't want to get stuck in that quagmire, you've got to be able to clean house.
- metadat 4y agoAgreed, frequently a single line "n.b." -style comment can save considerable future confusion, toil, and pain by clarifying either the original message intent or facets which might not be immediately obvious to a newcomer.
- grog454 4y ago> If you want your fence to stick around: document the rationale. That way, later people know if the reasoning still holds. And if you're at the point where the fence is being removed: might as well bite the bullet. The way I see it, the fallout from the removal (if there is to be any) was sealed at the moment it wasn't documented I have a somewhat embarrassing confession: I've done this with code I've written more than once. I've learned to thoroughly comment anything unintuitive even when I know I'm going to be the only one reading it.
- Thorrez 4y agoThe parable of Chesterton's Fence and the parable of cargo cults are in opposition to each other. One says "if you don't know what it does, don't delete it", the other says "if you don't know what it does, don't keep it".
- legalcorrection 4y agoThey both cut in the same direction: preserving the status quo. Don’t go around removing stuff you don’t fully understand. And don’t go around adding stuff you don’t understand.
- Thorrez 4y agoThe border between adding and keeping can get blurry. If you're creating a new module based on an existing module, is it appropriate to copy the boilerplate even if you don't understand all of it? What if you're renaming a file, do you have to understand everything in the file?
- legalcorrection 4y agoTo the first question, it depends. If it's something you're building for a business, and its reliability is important, then you probably should understand code you're copy-pasting. For a hobby project, it's probably not as important. The whole point of Chesterton's Fence is that there's wisdom encoded in the way things have been done. The previous guy who worked on the same module was probably somewhat competent, and in any case, the component was fulfilling business needs for all that time, so they were doing something right.
- ustolemyname 4y agoI disagree. In both cases the observer benefits from reaching beyond their current knowledge. They have the same solution.
- Thorrez 4y agoYeah. It is time consuming though. Thankfully our blame tool works well at my job.