[Review] Naming Things: The Hardest Problem in Software Engineering

In today’s post, I review Naming Things: The Hardest Problem in Software Engineering, by Tom Benner.

NOTE: At erikscode.space, book reviews do not contain affiliate links or paid advertisements. They are not written at the request of one of the authors or publishers, paid or otherwise. There are no incentives that would sway this review in a positive or negative direction. This review is based purely on the article's author's personal opinion.

Background

Naming Things

Phil Karlton once said

There are only two hard things in Computer Science: cache invalidation and naming things.

This is a fairly famous quote among software professionals and it refers to the difficulty in naming variables, functions, classes, projects, teams, and pretty much anything else requiring a moniker in software development. Naming things well is an incredibly important skill because it affects the way we think about the problems we’re solving and the code we’re writing.

Surprisingly, there is comparatively very little written about naming things in computer science outside of academic papers and (probably) diatribes in company Slack threads. Tom Benner addresses this gap in the literature by writing a brief and enjoyable book on the topic.

The Author

I had not heard of Tom Benner before but while researching this article I found his website, which led me to his GitHub showcasing a few highly-starred repositories and some non-trivial contributions to the Kubernetes repository. Between that and his LinkedIn profile, I think he has the credentials to be considered someone worth reading.

Ironically, if I’m reading it right, he added the current-context command to kubectl config. I say this is ironic because I never liked the word “context” for what this tool does and I’m about to recommend his book about naming things.

Overview

This is the first book I’ve ever read that tackles the topic of naming various things in day-to-day programming. The book intentionally avoids topics like case or naming projects or teams, narrowing the scope of the book to variables, functions, and classes.

The book identifies four attributes of a name that should be considered when naming things: understandability, conciseness, consistency, and distinguishability. The book starts by introducing the challenges in naming things, then defines the four name attributes, and ends by providing examples for applying the attributes.

Review: Great!

I really liked this book. I read it on my iPad so I’m not exactly sure how many “pages” it is, but I read most of it on a 2-hour flight and finished it up the next morning in about an hour, so it’s a very quick read compared to other books in our field.

General Notes

I think tech books often present their ideas dogmatically and with little room for nuance. However, I think that this topic necessitates a bit of dogmatism, and the author does a pretty good job of being prescriptive when necessary but leaving wiggle room when appropriate.

There was only one thing I disagreed with in the book. In the chapter about conciseness, the book advocates not including “how” a method is accomplished in its name and favors configuration arguments instead of multiple method names. The example given includes a CSV processor that can either process a CSV serially or in parallel processes. Specifically, the example given is:

# Bad
csv_processor.process_in_parallel(rows)
csv_processor.process_in_serial(rows)

# Good
csv_processor.process(rows, in_parallel=True)
csv_processor.process(rows, in_parallel=False)

I personally disagree with this specific example because I believe the implementation leads to a method that is too big (the body having code for both kinds of processing) or a method that is named inaccurately (it’s called process but it actually determines “how” to process the CSV and then calls the appropriate private method, presumably). In my opinion, I think the solution to this particular example is to have a CSVProcessor parent class and two child classes called SerialCSVProcessor and ParallelCSVProcessor that each implement a process method.

This is a super minor disagreement though, and the author has quite a few more years of experience than I do, so I would likely defer to their judgement if they were on my team. In fact, I will look for areas where this rule can apply and see if I still disagree with its sentiment.

Required Reading for Newly Minted Developers

I believe this book would be most helpful to a developer in their first year on the job. The concepts are neither too abstract nor too technical, and a new developer has enough experience to understand and appreciate the content of the book. I also think most seasoned developers would agree with the majority of the content, so it would be helpful for new developers to get on the same page with their more senior colleagues.

Conclusion

Pros: Very useful information concisely delivered.

Cons: None really

Overall: The first book on the topic at this level of accessibility. It’s useful to senior and junior developers alike (although moreso for the latter). Also, the references were quite interesting if you want a deeper dive on the topic.