Chesterton-proof your fences
Programmers are familiar with the idea that it is important to understand why a system or behaviour is the way it is before trying to change it. This avoids unintentionally breaking something you didn’t even realise was deliberate or necessary.
A pithy encapsulation of that wisdom is known as “Chesterton’s fence” after a passage from a 1929 book:
There exists in such a case a certain institution or law; let us say, for the sake of simplicity, a fence or gate erected across a road. The more modern type of reformer goes gaily up to it and says, “I don’t see the use of this; let us clear it away.” To which the more intelligent type of reformer will do well to answer: “If you don’t see the use of it, I certainly won’t let you clear it away. Go away and think. Then, when you can come back and tell me that you do see the use of it, I may allow you to destroy it.”
However, I prefer to think of this as a message not to the reformers, but to those who originally created the fence.
Had the original fence-builders left some legible mark of their intent, or a pointer towards where a description or documentation could be found, then the reformers’ work would not only be faster, but might result in a better decision.
I had an encounter like this at work the other day. A calculation was producing outputs that had us scratching our heads. Was the code wrong? Was it just bugged, or had we misunderstood the requirements at the time? Or were we misunderstanding something in the present?
Looking at the source code, I encountered this comment:
/**
* TODO: find textbook citation
*/
With no help from my past self, I hit the bookshelf and found the relevant chapter. As it turns out, we were doing everything correctly, and the behaviour, while appearing counter-intuitive in the edge case, was solid.
(And thanks to this incident, that comment was replaced with couple of paragraphs of explanation and a precise citation.)
Don’t make your future self, or somebody else, guess at what you were thikning and why you were doing it. It might not be so easy to attach comments to fences*, but in software, it is very easy. All it demands is that you think about what you’ve done and explain it, however briefly.
*Although, I do dearly wish that our built environment was more accessibly annotated! I don’t mean archived plans in local government filing cabinets; I mean plaques and QR codes linking to explanations of what material a building was made of, how a plaza was shaped, the context in which a street was widened. Many of the answers to these questions will be banal, bt that in itself is something to learn about the environment we live in.