Explaining Variable
June 24, 2021
An Explaining Variable is a code-level pattern which reduces the need for code comments, making your software a little more self-documenting.
Here we have a function with some non-obvious business logic, with a comment to explain what’s going on:
And here’s how we can replace that code comment with a couple of explaining variables:
We no longer need that code comment; we’ve replaced the explanation in the comment with two explaining variables.
The benefits of explaining variables
Why might we prefer explaining variables over code comments? Because with code comments we end up with two parallel sources of truth - what the code is doing, and what the comment says. Over time these two sources of truth have a tendency to diverge.
To illustrate how this can happen, we’ll explore a scenario where we need to update the logic in this function later on. Let’s say we can no longer assume that shipping by air implies same day delivery. To reflect these updated business rules, we simply remove the second part of the conditional in that if
statement:
Looks good, right? The implementation is correct. But we forgot to update the comment and it is now out of sync with the implementation. Oops.
This phenomenon of comments and implementation diverging occurs a LOT. It’s really easy for a developer to skim over comments when making a code change and forget to update them. There’s even a saying for this - “code comments are lies waiting to happen”.
In contrast, when working with the version of our implementation which uses explaining variables, the code remains accurately self-documenting:
Explaining Method/Function
We can apply this same self-documenting approach with methods or functions - rather than commenting a block of code to describe what it does, we can create a method or function with an explanatory name.
Here’s a function which is performing a few different steps, described using comments:
We can replace those comments with explaining functions:
These explaining functions (or methods) have the same benefits as explaining variables - they reduce the need for explanatory comments.
References
Martin Fowler introduced the concept of explaining variable in his Refactoring book - it’s covered briefly in his Refactoring.com catalog. I find myself recommending this refactoring a lot and wanted a more detailed discussion of the pattern to point to, hence this post.