Zee Spencer

Ambiguity In Code Is an Opportunity to Refactor

There's a common design principle that states "Design the system to prevent errors from occuring." Lean manufacturing calls this Poka-yoke. Interaction design calls these forcing functions.

Since a much of the time building software is spent reading code, it's important to decrease the amount of errors in understanding while we read.

One way to do this is to decrease ambiguity. Consider the & symbol in Ruby. It's a method call on some ruby classes, a unary operator for converting objects to blocks, and a binary operator for calling the & method without using a ..

In order to properly understand what the & is doing you have to figure out which of it's three roles it's fulfilling. If it's a binary operator or a method call you also must understand what that method is in the context of which object it's using.

For example, 1 | 5 is a bitwise or operation, while [1,3,5] | [3,5,7] is a [set union](http://en.wikipedia.org/wiki/Union(settheory).

While we learn to infer this over time there is some cognitive overhead as we read. To combat this, I propose we take a cue from the zen of python, which states explicit is better than implicit. In that spirit, python provides two ways to do set intersections: the & operator, and the intersection function.

Since ruby does not always provide named variants for ambiguous symbols this provides us with an opportunity to refactor. When we encounter ambiguity, maybe it's time to extract a method to describes the operation more explicitely than | or &.


Browse posts about:

Want to get notified when I publish new articles or update old ones? Subscribe to my newsletter. It's a weekly-ish set of interesting links with a short essay on programming, design, technical leadership, or anything else that strikes my fancy.

Not sure? Read the archive.