Turning implicit understanding into explicit code is a great productivity & quality step.

Let's talk about some whys and hows for that idea.

As we forge into the topic, please do remember, this is just comfort food, not the main story. I proudly support my friends & family who are working for change in the world, and encourage them to keep at it.

Stay safe.
Stay strong.
Stay kind.
Stay angry.

Black lives matter.

An implicit understanding is anything a skilled geek would have to be told before being set loose in your codebase to make a change. Implicit understandings take lots of different forms, but at their simplest, they often involve hidden correlations.

Probably the most common form of implicit understanding is related to the smell we call primitive obsession. You'll see a series of methods, and each method takes the same three arguments, an int for the ID, a string for the descriptor, and a decimal for the amount, let's say.

Those three arguments are actually correlated: together, they uniquely identify a line item on an invoice. But there's no "LineItem" thing. Instead, we just pass and pass and pass those three arguments. *We* know they're correlated, but the code doesn't *say* they're correlated.

The fix here is pretty straightforward: Make a LineItem, and pass those instead. Now, my senior geek doesn't need to be told about that correlation, it's right there in the code. We have made our implicit understanding of the code into something direct and explicit.

Notice, too, even in this simple case, the fix may actually be just a first opening step in a long sequence of impressive transformation: perhaps those six methods that now all take a lineitem are best expressed as methods *on* a lineitem. They're things lineitems know how to do.

This "follow-up opening" aspect of converting implicit to explicit is quite common, no matter the underlying form of the case. The fix for these cases will ofen serve as a kind of change gateway, freeing us to move much more rapidly as we reshape the code for our customers.

Another common case of implicit and explicit: an object with a default constructor and a bunch of setters, some of which *must* be set to use that object correctly. Teammates who've been there a while know this, but your noob senior will have to code-study or be told.

Again, there's at least one straightforward fix: kill off that default constructor and replace it with one that requires all the settings that must be present. You make an implicit runtime dependency an explicit compile-time one. (There are other fixes possible, too.)

Another variant: like before, we have an object with setters, and one of those fields must be set to a legit value, but only if we're going to call that one method that requires it.

Here there are at least three fixes. 1) Always require it, via constructor. 2) Require it to be passed to that method. 3) Create a wrapper for that method's purpose and give *that* guy the required constructor argument.

These cases are all fairly modest, but the implicit->explicit thing is often present in other forms, more rich, with more variants, more complexity, and here's the thing: even greater costs in terms of our productivity.

Now that everyone's so service-crazy, significant apps are really many different programs running in orchestra. The user experiences one app, but the codebase is twenty apps big.

And every single program maintains its own configuration block, typically in a profile or registry system, pointing at all the others that it's supposed to be using. The implicit understanding? All those URL strings have to be correlated across all those programs. Whoops.