Afterwood

The second most popular joke in programming reminds us that naming is hard. (In a Programming Jokes Top 10, this would be the other one.) That hasn’t stopped some people apparently attempting to overcome this problem by applying a ‘formula’, which generally involves concatenating various Computer Science and business terms together and finally appending one of Manager, Service, or Provider to give it extra gravitas. The problem appears to be particularly acute in the enterprise world of Java and C#, where Design Pattern Bingo is a popular pastime.

What triggered this latest Afterwood was working in a C# codebase where there had been a need to write tests for code that invoked DateTime.Now(), which is a static method that returns the current date and time. Doing a spot of software archaeology, I noticed there had been an initial attempt to work around the non-deterministic nature of this method by doing an assertion in the tests with a small tolerance, but the woefully underpowered CI server put paid to that as the tolerance was widened every time the tests took longer than usual to run.

The solution had been to mock out the method call entirely and return a fixed value in the tests, and the real date and time in production, by introducing a suitable interface and pair of concrete implementations. Naturally, if you’re looking to name an interface for such an abstraction you’re probably thinking, ‘What do I call an interface that provides a date and time value?’ and so you go with the first thing that pops into your head – IDateTimeProvider. Wait, that’s not right…

I don’t know for sure how this name really came about but the seemingly robotic approach to so many names in the codebase suggested they were driven by terms from the solution domain instead of the problem domain or, say, The Real World™. I posited on the team chat that the IDateTimeProvider abstraction was basically just a ‘clock’, and that was largely met with approval, so the refactoring went straight in. It also opened the door for a further discussion about naming, metaphors, and typing less. (Strunk famously tells us to “omit needless words” which has the marginal added benefit of less wear and tear on the keyboard.)

The world of software is entirely virtual in nature and therefore we must rely very heavily on metaphors as a source of inspiration for how we name stuff. The great thing about the world of horology is that it provides us with a whole host of physical devices to draw from. ‘Clocks’ and ‘calendars’ allow us to discover the current time and date, ‘stopwatches’ allow us to measure time, and ‘timers’ can be used to notify us when a period has elapsed. Clocks come in many different shapes and sizes, and degrees of precision, so if you want to capture that in your naming scheme you could use ‘wall clock’ for the low-end and a highfalutin’ name like ‘chronometer’ for the high-end.

While the name IDateTimeProvider might on the surface appear to be sufficient for the task, I argued that it’s too abstract. This also gave the perfect opportunity to play one of my Programming Quote Top Trump cards [Oldwood23] from Edsger Dijkstra:

Being abstract is something profoundly different from being vague … The purpose of abstraction is not to be vague, but to create a new semantic level in which one can be absolutely precise.

The point of using a metaphor is to allow us to be more precise about the kind of thing we’re talking about by borrowing from a recognisable domain. When talking to the business we would expect to use a ‘ubiquitous language’ and expect the problem domain to provide many of the terms we use in our code. When it comes to the technical domain, something which the business will have almost no input on, we are left to our own devices. This does not absolve us of the responsibility to be clear about what we mean in the code. If anything, we have to work harder because it’s not handed to us on a plate. (Pro Tip: always keep a thesaurus on hand for inspiration [Oldwood15].)

One comment to my suggested renaming was that it didn’t really matter because although the code said IDateTimeProvider, in their head they mentally translated that into ‘clock’ anyway. This misses one of the key points about why we refactor code – to ensure that it always reflects the best understanding we have of the domain at any given point in time. If your best mental model is currently a clock, then that’s what it should be called (for now), don’t make people waste brain cycles second-guessing what might have been meant.

And it is just a model, and an imperfect one at that. Playing my second Quote Top Trump card – George Box – we are reminded that “all models are wrong, some are useful”. In some scenarios, it could be a poor metaphor because a clock may conjure up a different kind of device, such as in electronics where the clock is an oscillating signal, more like a metronome ticking left and right, than a pair of hands slowly turning around a circle. Fortunately, the same stable that brought us the notion of a ubiquitous language also helps us resolve our conflict here by applying a ‘bounded context’ around our codebase so that the interpretation is the most fitting one for our part of the business instead of encompassing every potential definition covered by Wikipedia.

Hopefully, the use of the clock metaphor will be timeless, but as we get older we do need to be aware of anachronisms, such as the nautical terms I wrote about back in June [Oldwood23]. Once upon a time, Hi-Fi Separates (where the turntable, tape deck, CD player, amp, etc. were all distinct devices connected by standard RCA cables) was a common metaphor for a component-based architecture but that seems to have died out as headphones (except on public transport) are the only accessory for the ‘modern Hi-Fi’, aka the phone. And if you’re still thinking of using a floppy disk for your save icon, I’m afraid that ship sailed a long time ago!

References

[Oldwood15] Chris Oldwood, ‘In The Toolbox – Dictionary & Thesaurus’, CVu, 27(3), July 2015. https://accu.org/journals/cvu/27/3/oldwood_2116/

[Oldwood23] Chris Oldwood, ‘Afterwood: Quote Top Trumps’, Overload 175, June 2023. https://accu.org/journals/overload/31/175/oldwood/

Chris Oldwood is a freelance programmer who started out as a bedroom coder in the 80s writing assembler on 8-bit micros. These days it’s enterprise grade technology from plush corporate offices the comfort of his breakfast bar. He has resumed commentating on the Godmanchester duck race but continues to be easily distracted by emails and DMs.