(Un)Forgettable rules

In code, let’s say it’s easy to create a system. You wire up all the bells and whistles and things work great! Let’s call this piece of work A.

A month goes by and it’s time to extend that feature, add onto it, or even just contribute some additional piece of behaviour in that system. Let’s call this piece of work B.

In A, you probably established some patterns or standards for other code to follow, these are the rules in this context. The idea is that you spent some significant amount of time solving this problems and building abstractions to be reused in the future. Or maybe you even found a trap you want to prevent other’s from falling into. Whatever the reason, you created abstractions to fix a current or future problem.

But here’s the catch.

There’s nothing enforcing these abstractions.

Sure if someone spent the time to read through your implementation and comments and wisdom, they might gleam the insight you once held. But the reality is that a lot of people are not writing there own code now a days, and it can be difficult to acquire someone else’s headspace, especially if your in a crunch. I will say because of these details, it’s easy to miss useful and important abstractions which the system has already created. It’s logical to predict that B will go off the rails in one or more ways, potentially solving the same problems and falling into traps A already encountered.

Rules should be

• lean
• forgettable
• enforceable
• obvious
• non-negotiable

I recently ran into a small collection of these rules packaged into an elixir library called jump credo checks . This library describes itself as a “collection of opinionated Credo checks aimed at improving code quality and catching common mistakes in Elixir, Oban, and LiveView”. Let’s unpack that a little bit:

To understand what a Credo check is, we first need to understand what Credo is. Credo is “a static code analysis tool for the Elixir language with a focus on teaching and code consistency”. A static code analysis tool looks at your code and talks about it. It can give you insights on refactoring opportunities, show inconsistencies in naming, and even enforce a desired coding style. Connecting the jump_credo_checks to Credo, a Credo check could look like this:

Jump.CredoChecks.TestHasNoAssertions: Alerts on ExUnit test blocks that contain no assertions.

We can learn a number of things from this example.

1. Credo checks are lean, they look for one thing and one thing only
2. A good name describes the functionality and a description helps explain the why and what

This check is pointing out the obvious: a test should always have an assertion of some kind. Otherwise it’s not much of a test is it now?

Most people might take this for granted or say it’s a given, but that’s the entire point. If it’s intended to always happen, let’s require it to be that way. This way we, or an llm, or a new team member, or literally anybody else can never make this mistake.

There are truths in the codebase that we hold as self-evident.

But we can do better. Let’s try again.

There are truths in the codebase that we require as self-evident.

What does that even mean?

Well you can write your own code and pursue your implementation, but there are small things which need to be upheld for the sake of the system, sanity, and whatever reason your particular use case or problem demands.

This Credo check, unspoken rule, whatever you want to call it is not preventing you from solving a problem, but rather forcefully encouraging you towards an agreed upon standard.

This style of preventative, consistent, transparent, and thoughtful coding is more important now than ever thanks to LLM’s and their harnesses compiling, running, and testing our code. If our job is changing to provide the available and necessary context to the llm, for it to do it’s best work, than small checks can help guide it in a cohesive manner to keep it on the right path, make reviews faster, and catch easy and simple mistakes.