Recently I’ve been thinking a lot about explaining code. This mostly comes down to avoiding potential issues when someone else comes to read it.

I think there are three things that can be done to help make code understandable:

  1. Use names, word, and structure that aid readability and understanding.
  2. When that’s not possible, add comments that explain why the code is as it is or doing what it does.
  3. When that’s not possible or enough, create accompanying documentation (doesn’t have to only be written text) that provides the additional information.

Mostly, option 1 should be enough. Option 2 should (ideally) be an occasional solution. Option 3 should only be an exceptional case.

And then I read parts of scripture along the lines of “They did [X], because of [Y]” but from my perspective in space and time, I have no idea how ‘X’ and ‘Y’ are at all related.

I could use some comments and explanation.

Fortunately, I have multiple translations available to me and many have accompanying footnotes and commentary. I also have many separate commentaries and other resources available to me, and have enough knowledge to know where to go to find more information.

But what about those new to the bible? What if the only bible they have is one without any notes or commentary? Is this a bit like new developers thrown into a codebase they don’t understand and with no one to ask? In these situations their progress is slowed and they could end up making costly mistakes due to a misunderstanding.

Yes, I appreciate that there is value from some parts of scripture not having simple, obvious, and immediate explanations. So the analogy falls down there. But, all analogies fall down somewhere.

I don’t want to dismiss either the ability of the Spirit to work through any translation of scripture, nor your ability to write code that could never be confused or misunderstood. I just wanted to note the similarity in my mind and the importance of giving people the information and support they need to get the most from what they’re reading.