Chesterton's middle finger

Personal website of Martin Tournoij (“arp242 ”);<br>writing about programming (CV) and various other things.

Working on<br>GoatCounter and<br>more –<br>GitHub Sponsors.

Contact at<br>martin@arp242.net or<br>GitHub.

The Chesterton’s fence analogy says that you need to be careful to change<br>things if you don’t understand why things are the way they are, because there<br>may be good reasons you haven’t considered yet. This is broadly good advice in<br>many different contexts, including programming where it can be easy to “fix”<br>some weird code only to discover there was a reason for the weirdness later on<br>when things break.

This is Chesterson’s middle finger:

# List all commit body content (but not the subject line)<br>% git log --no-merges --format=format:'%b' | sed '/^$/d' | wc -l<br>295

That’s 295 lines of commit text over the last 13 years. In total. The commit<br>subjects are usually just “fix page A” – even for huge changes – and are<br>pointless. If I manually remove some dependabot, “revert commit”, and “fix typo”<br>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.

This is Chesterson’s middle finger: “Yes, we did all these weird things and<br>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<br>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,<br>but that was just as communicative as the commit log. Never have I sympathized<br>more with Jack Bauer’s methods to extract information and I regret not employing<br>some of them.

There are unfinished refactors. There are left-overs from removed features.<br>There are features that were added but never linked/used but are still in the<br>code. There are features no one seems to be using. Overall it seems to suffer<br>quite badly from Chesterton’s gap (“There isn’t a fence yet? Lets build<br>fences!” without asking if a fence is actually needed).

Everything is just a big fat middle finger.

Writing well is hard. Writing something vaguely passable is not. By and large<br>there are three questions to answer: “What are you changing?”, “why are you<br>changing it?”, and “why is this a good solution?”

Sometimes “Implement new feature X” is enough, although it’s rare there is<br>nothing more to say – most of the time there is something to say about how/why<br>it’s added as it is.

If you’re fixing a bug, refactoring or changing things, or making some other<br>substantial change then it’s very rare there isn’t at least a paragraph or two<br>to comment on the “what’s changing, why change it, and why is this good?”<br>questions.

Writing this is not an optional extra; it’s part of the job. If you’re not doing<br>it then you’re not doing your job as a software developer. It doesn’t need to be<br>eloquent. It doesn’t need to be perfect English. It doesn’t need to be a<br>comprehensive essay on the nature of reality. It’s okay to forget something<br>(although better if you don’t). It just needs … something. Any half-way<br>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<br>finger.

Other Programming posts 22 Feb 2021 Go is not an easy language

7 Jan 2019 Testing isn’t everything

16 Nov 2024 Against best practices

29 Nov 2020 Stupid light software

22 Mar 2019 Easy means easy to debug

10 Dec 2020 Bitmasks for nicer APIs

25 Nov 2020 An API is a user interface

25 Apr 2020 Storing files in .git

5 Dec 2019 Good comments read well and are to the point

4 Sep 2016 YAML: probably not so great after all

7 Oct 2019 On being the right size

7 Feb 2016 The downsides of JSON for config files<br>Other Workplace posts<br>18 Feb 2021 Downsides of working remotely