The title of the post is the title of the book that I wanted to publish for quite some time now. While I was thinking about phrasing and gathering content, somebody else beat me to it with Naming Things: The Hardest Problem in Software Engineering. The main issue that I wanted to solve is now solved. Programmers don’t have an excuse for poor naming anymore.
In light of this event, I’ve decided to make small complementary post out of the materials that I have gathered and move on, focusing on Next Generation Shell.
Me and Naming
I have over 20 years of professional experience in programming. During that time, as many others, I’ve also noted the struggle when it comes to naming.
Here is a list of my accepted naming contributions to various projects.
- iterators – function shoes_in_my_size naming 2020-02-16, “The Rust Programming Language” book
- Constructors – Get_Contents() method is misnamed 2020-02-23, MS C++ Documentation
- Rename howMany() to countSelected() 2023-01, MDN
- nilJson naming issue in readme 2023-04, Otterize
Naming Things, the Book
I skimmed Tom’s book to understand how similar it was to what I was about to write. Quite close. If you are struggling with naming, go and read it.
There is some amount of fluff which I think my book would have less. Example: convincing people that naming is important while they are already reading the book.
Overall, I do recommend the book though.
Especially I recommend this book to AWS as an organization, I guess along with other books about code quality in general. AWS, your de-prioritization of code quality is staggering. I mean observable output here, not the stated “Insist on the Highest Standards”.
6.2.6 Use accurate parts of speech
Adding negative example from AWS:
https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/crpg-ref-responses.html
SUCCESS and FAILED are not the same part of speech.
7.2.3 Omit Metadata
Additional reason to exclude data type from the name is to avoid additional changes anywhere in the code except for the declaration.
elt in itemsIs items a list here or a set? Probably not important, the code should work with either. On the other hand, changing data type from list to set in the following example will make the code incorrect:
elt in items_list8.2.4 Use similar names for similar concepts
Adding negative example from AWS, which time after time fails to give consistent names across their APIs.
How do you limit number of results from an API? MaxResults, maxResults, MaxRecords, MaxItems, Limit, limit, … Details at AWS API pagination naming.
It looks like consistent naming is valued less than independence of teams and ability of teams to perform uncoordinated work.
8.2.5 Use consistent antonyms
Adding example.
When I’ve got to name Option type (represents a container that can hold a value or can be empty) in Next Generation Shell, I went with straightforward antonyms.
- Box (super type)
- EmptyBox
- FullBox
Authors of other languages preferred other naming conventions:
Scala: Option, None, Some
Haskell: Maybe, Nothing, Just
Perspective
Information Loss
In my perspective, giving inadequate names is part of a larger issue – Information Loss. Each time you give a name, think which information is now in your head which will be helpful to the reader of the code. If you don’t phrase it concisely and precisely, information loss occurs between your head and the code you are working on. There are several common types of errors one can make:
- Don’t provide enough information. Causes the reader to investigate in order to recover the information.
- Provide wrong information. That’s the worst, it’s misleading the reader.
- Provide too much information. The reader then must sift through the information to get to the relevant parts.
API
Sometimes it’s useful to think of methods as an API. That’s why method names shouldn’t include implementation details (with rare exceptions when they are important to the caller). Think of methods’ names and parameters’ names as a short version of API specification.
Identifiers
Tom’s book deals with naming identifiers, such as functions, classes, variables, etc. One step before naming an identifier is the question whether there should be an identifier.
Avoid Naming
Sometimes, the additional cognitive load is not worth it.
# Bad
chairs = fetch_chairs()
sorted_chairs = chairs.sort()
# also, now have to use the longer identifier in the code below
# Good
chairs = fetch_chairs().sort()Apply your judgement of course. If it’s a 20 step process, additional identifiers in the middle do contribute to understanding. You still probably don’t want an identifier for each and every step of the calculation.
Do Name – Magic Numbers
Avoid magic numbers through naming. Please ignore whether result is a good name 🙂
# Bad
if result == 126 { ... }
# Good
NOT_EXECUTABLE = 126; # Or better, part of an Enum
if result == NOT_EXECUTABLE { ... }Do Name – Repetitive Code
If you notice code that repeats, with rare exceptions, you should refactor your code extracting that code to a function or a method with a name.
Several Identifiers
Sometimes a function, a method, or a class do several things. In this case, you might struggle to name it. In a perfect world, the solution to this is refactoring to appropriate pieces.
Test Your Naming
You just named something: a function, a method or a class. Is there a change around the code that would make the name wrong? What if you copy+paste the named piece of code to another project? Would you need to change the name?
# Bad
function start_yellow_cars(cars) { ... } # The function doesn't know or care about the color
yellow_cars = ...
start_yellow_cars(yellow_cars)
# The change that would highlight the wrong naming
# while keeping the code completely functional
function start_yellow_cars(cars) { ... }
my_cars = ...
start_yellow_cars(my_cars)
# Good
function start_cars(cars) { ... }
yellow_cars = ...
start_cars(yellow_cars)Common Naming Mistakes Observed
Tooling
I highly recommend using IDEs that “understand” the code enough to be able to refactor/rename (classes, methods, functions, parameters) as opposed to text editors which can not assist with renaming to the same extent.
Hope this helps. Happy naming!
Ilya's blog 