Naming Things Without Pain

Naming variables and functions is an essential yet often overlooked aspect of programming. Despite its importance, it can consume a significant portion of a developer's time. Initially, I struggled with the naming process, spending minutes on a single variable name and renaming it multiple times during code reviews. However, I eventually discovered two critical rules that greatly reduced this friction.

The first rule is to name the thing by what it is, not what it does. For instance, a boolean value should be named as a fact about the world, such as isLoading, hasPermission, or canEdit. If you find yourself writing checkPermission, it might be more appropriate to create a function instead of a flag. The second rule is that the length of a name should match its scope.

For example, a loop index can be a simple i, a variable used a few lines later can be id, and a module-level export that appears in many files requires a more descriptive name like InvoicePaymentStatus.

Consistency is key in naming conventions. Rather than striving for cleverness, it's better to maintain a uniform naming style. I find it helpful to keep a small mental table to guide my naming decisions:

- Booleans: is/has/can/should

- Functions: verb first

- Collections: plural

- Handlers: on + event

Once the naming shape is determined, filling in the blanks becomes a straightforward task rather than an open-ended creative challenge. To test the effectiveness of a name, read the line where the thing is used instead of where it is defined. A line like if (user.isEmailVerified) { ... } reads much better than if (data.flag) { ... }.

I have also abandoned the practice of encoding the type in variable names, as it becomes redundant and misleading when the type changes. Instead, I prefer to name variables based on their content, such as users or names. Similarly, prefixes like IUser or suffixes like str or int are unnecessary and can lead to confusion when the type changes.

Often, naming difficulties are a sign of poor design. If a function like processAndValidateOrder cannot be cleanly named, it usually indicates that the function is performing multiple tasks. Breaking it down into separate functions, such as validateOrder and processOrder, resolves the naming issue and clarifies the purpose of each function.

Renaming is an essential part of the development process, and modern editors make it a non-event. I find it beneficial to rename symbols, run tests, and commit frequently to minimize the impact of a slightly incorrect name. Embracing a naming aggressiveness and allowing the tool to handle the renaming process can save a significant amount of time.

Ultimately, the cost of a poorly named variable or function is the frustration experienced by every future reader, while the cost of a rename is merely a single commit. I do not strive for perfect names on the first attempt but rather write something temporary, get the logic working, and then rename once the code's purpose becomes clearer.

In summary, I follow a short checklist when naming variables and functions:

1. Does it read well at the call site?

2. Is it a fact (boolean) or an action (function)?

3. Is the length appropriate for its scope?

4. Does it avoid encoding the type?

5. If naming is difficult, is it doing too much?

If a name fails these checks, I stop trying to find the perfect name and instead consider whether the function should be split into separate responsibilities.