Three Years — Part 1: Names and Types
Working in enterprise software engineering for the last three years, I’ve started to recognize a few patterns in the projects, systems, and teams I’ve worked with. In my next few posts, I’ll describe some of those patterns, both technical and personal, and their impact on my life of a software engineer.
Names and Types
“There are only two hard things in Computer Science: cache invalidation and naming things” — Phil Karlton.
I’ll start things off with technical naming. The topic is well-discussed elsewhere, but this would feel incomplete without mentioning it since it’s proven to be one of the most important lessons I’ve learned as a novice, yet is still a common topic that comes up in software peer review.
I’ve seen poorly-named variables and Java classes cause embarrassing outages and data loss, routinely confuse engineers and make people cringe when explaining the behavior of an API. By developing a few naming habits and avoiding others, you might help your coworkers hate their codebase a little less.
A Note on Associative Memory
Stepping back a bit first, most of the following aims to make code read in such a way that it requires as little cognitive overhead to understand the behavior of a system.
There is a finite amount of context that the human mind can keep in fluid memory when reading a block of code; descriptive naming helps form a clear picture of actors and forces that control the flow of a program without unnecessarily cluttering their limited pool of Associative Memory. This is important for your own codebase, but the effect is amplified when working with an unfamiliar system.
The below sections will list a few instances where you can avoid mental clutter by avoiding a few naming anti-patterns.
Project Codenames
API, class-level, and variable names that are a concise description of their behavior help software more grow cohesively and minimizes mental effort. Project codenames, on the other hand, describe the business motivation behind a particular source of complexity.
The following example is inspired by a former team of mine, with names changed: Imagine you’re a junior engineer working on a web page that changes behavior depending on the user’s preferences (for example, iGoogle). You’re browsing through the project to fix a UI glitch on something, lets call it a “Greeting Widget”, and come across a Java class named EagleUtil that seems to be related to some parts of the Greeting Widget’s behavior. Any idea what’s inside? Nope!
EagleUtil.java:public String getGreetingWidgetColor(String configKey)
It turns out, five years ago, “Project Eagle” added a system for overloading the behavior of the Greeting Widget. Since then, every developer that has come close to the Greeting Widget needs to recall Project Eagle to understand the behavior.
Entities and types that describe their effect on the behavior of the system, on the other hand, help engineers safely ignore it in most cases, yet act as a beacon to interested parties that the solution to their problems may lie inside.
WidgetUIConfigFactory.java:public WidgetUIConfig getGreetingWidgetUIConfig(User user)
The above naming convention and structure is easier for an engineer fixing a network latency bug to ignore, but attracts the eye of those fixing UI bugs.
An argument against neglecting project names is a loss of motivational information. That’s true, but a comment or, better yet, descriptive revision control message with links to project documentation is probably just as good.
Naming Real Units
It’s not uncommon to vary behavior on a physical unit, such as time, using an int or short. Common scenarios include caches and network call timeouts.
short cacheTtl = 60;In the example above, is it obvious to you how long the cache lives? Nope!
Primitives with names that include or suggest their unit are a great way to reduce unnecessary cognitive overhead. In my experience, debugging problems related to time, such as unexpected cache misses, etc, is almost always done during moments of stress such as an outage when every moment wasted hurts your business.
short cacheTtlSeconds = 60;By referring to the unit in the variable’s name, there’s little room for confusion in what the expected behavior should be.
Using Types Liberally
Similar to naming Real units, using named types, enums, or similar structures is another way for code to document itself and read like a book.
In the following example, and engineer is tasked with adding optional text weight to a button. A common pattern is to introduce a Boolean flag to enable or disable the different weights, but there are a few issues with doing so.
Widget getGreetingButton(boolean isTextBold)Passing booleans around to enable or disable features causes a few problems:
- It’s hard to expand. Following the principle of “Design for expansion not modification” — adding an additional switch is easy if you’re switching an Enum.
- In my opinion, it’s ugly. A method signature of String, Boolean, Boolean makes for some ugly and hard to read code, especially in tests where several identical method calls are stacked on top of one another.
assertThat(getGreetingButton(true).getWeight(), is('bold'));
assertThat(getGreetingButton(false).getWeight(), is('normal'));Instead, an enum which represents the feature, not whether or not it’s enabled/disabled, extends more naturally.
public Widget getGreetingButton(TextWeight textWeight)...enum TextWeight { normal, bold, italic }...weights = Sets.newHashSet(TextWeight.bold, TextWeight.italic);
and reads much more naturally:
assertThat(getGreetingButton(TextWeight.bold).getWeight(),
is(‘bold’));What’s Next?
To wrap it up — staying away from a few tempting naming anti-patterns can help increase readability and lend to easier future extension at no real cost.
In my next post, Part 2: Productivity (coming soon) I talk about some things I’ve learned in my first three years as a software engineer to stay focused and get stuff done.
