Chesterton’s middle finger

切斯特顿的“中指”

The Chesterton’s fence analogy says that you need to be careful to change things if you don’t understand why things are the way they are, because there may be good reasons you haven’t considered yet. This is broadly good advice in many different contexts, including programming where it can be easy to “fix” some weird code only to discover there was a reason for the weirdness later on when things break. “切斯特顿的栅栏”（Chesterton’s fence）这一类比告诉我们，如果你不理解事物为何如此存在，在改变它们时就需要格外小心，因为背后可能存在你尚未考虑到的充分理由。这在许多领域都是一条通用的金玉良言，包括编程——你很容易因为想“修复”一段奇怪的代码，结果在系统崩溃后才发现，当初之所以写得那么奇怪是有原因的。

This is Chesterson’s middle finger: 这就是切斯特顿的“中指”：

# List all commit body content (but not the subject line) % git log --no-merges --format=format:'%b' | sed '/^$/d' | wc -l 295 （列出所有提交正文内容，不含标题行）

That’s 295 lines of commit text over the last 13 years. In total. The commit subjects are usually just “fix page A” – even for huge changes – and are pointless. If I manually remove some dependabot, “revert commit”, and “fix typo” commit bodies it’s just 167 lines. That’s about one line a month. There is no other documentation. There are barely any comments in the code. 过去 13 年里，总共只有 295 行提交说明。提交标题通常只是“修复 A 页面”——即使是针对巨大的改动也是如此——毫无意义。如果我手动剔除掉一些 dependabot、撤销提交和修正拼写的说明，剩下的只有 167 行。平均每个月一行。除此之外没有任何文档，代码里也几乎没有注释。

This is Chesterson’s middle finger: “Yes, we did all these weird things and we’re not telling anyone why. Haha fuck you.” 这就是切斯特顿的“中指”：“没错，我们做了所有这些奇怪的操作，但我们就是不告诉任何人原因。哈哈，去你的。”

This is not the first time I’ve seen a less-than-useful commit log, but it is the first time I’m hired after everyone else left. There is no one to ask. In theory there was a three week handover period from the previous developer, but that was just as communicative as the commit log. Never have I sympathized more with Jack Bauer’s methods to extract information and I regret not employing some of them. 这并不是我第一次见到毫无用处的提交日志，但这是我第一次在所有人离职后才入职。没人可以询问。理论上，前任开发者有三周的交接期，但那段交接过程和提交日志一样缺乏沟通。我从未像现在这样同情杰克·鲍尔（Jack Bauer）那种获取信息的方式，我甚至后悔没能用上他的一些手段。

There are unfinished refactors. There are left-overs from removed features. There are features that were added but never linked/used but are still in the code. There are features no one seems to be using. Overall it seems to suffer quite badly from Chesterton’s gap (“There isn’t a fence yet? Lets build fences!” without asking if a fence is actually needed). Everything is just a big fat middle finger. 代码里有未完成的重构，有已删除功能的残留物，有添加了却从未链接或使用但依然存在的代码，还有似乎没人使用的功能。总的来说，这似乎深受“切斯特顿鸿沟”（Chesterton’s gap）之苦（即“还没栅栏？那我们建个栅栏吧！”却从不问栅栏是否真的需要）。这一切简直就是一根巨大的、粗鲁的中指。

Writing well is hard. Writing something vaguely passable is not. By and large there are three questions to answer: “What are you changing?”, “why are you changing it?”, and “why is this a good solution?” Sometimes “Implement new feature X” is enough, although it’s rare there is nothing more to say – most of the time there is something to say about how/why it’s added as it is. 写出高质量的文档很难，但写出勉强过得去的东西并不难。大体上，只需要回答三个问题：“你改了什么？”、“为什么要改？”以及“为什么这是一个好的解决方案？”有时“实现新功能 X”就足够了，尽管很少有情况是无话可说的——大多数时候，关于它是如何添加的以及为什么要这样添加，总有些东西值得一说。

If you’re fixing a bug, refactoring or changing things, or making some other substantial change then it’s very rare there isn’t at least a paragraph or two to comment on the “what’s changing, why change it, and why is this good?” questions. Writing this is not an optional extra; it’s part of the job. If you’re not doing it then you’re not doing your job as a software developer. 如果你在修复 Bug、重构代码、进行改动或做出其他重大变更，那么几乎不可能写不出那一两段话来解释“改了什么、为什么要改、为什么这样改很好”。写这些不是可有可无的额外工作，而是工作的一部分。如果你不做，那你作为软件开发者的本职工作就没做好。

It doesn’t need to be eloquent. It doesn’t need to be perfect English. It doesn’t need to be a comprehensive essay on the nature of reality. It’s okay to forget something (although better if you don’t). It just needs … something. Any half-way serious attempt will be infinitely better than nothing at all. If you do nothing at all then you’re just giving everyone after you the finger. 它不需要文采斐然，不需要完美的英语，也不需要成为探讨现实本质的宏篇大论。偶尔遗漏一些东西也没关系（当然最好别遗漏）。它只需要……写点什么。任何稍微认真一点的尝试，都比什么都不写要好得多。如果你什么都不做，那你就是在给所有接手你代码的人竖中指。