Post Syndicated from arp242.net original https://www.arp242.net/chestersons-finger.html

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.

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.

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.

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.

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.

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. 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.