The Art of Naming Things in Code: Ditch Single-Letter Variables and `utils` Classes

Choosing compelling names for code elements is crucial, but avoiding certain naming pitfalls can save you significant headaches. Single-letter variables like 'x' or 'i' were once acceptable when programming closely resembled mathematical notation. However, software today is read and edited far more frequently than it's originally written.

Modern Integrated Development Environments provide instant auto-completion, and wide screens offer ample space, rendering the need for cryptic abbreviations obsolete. For example, using 'per' instead of 'periodDays' hides the intent, making the code harder to understand.

Another outdated practice is embedding types or prefixes into variable names. The concept of Hungarian Notation, which required prefixing variable names with data types, emerged before modern strong typing languages. Today, compilers and IDEs know the type, and adding it to the variable name only adds clutter. Similarly, prefixes like 'I' for interfaces or 'Base' for parent classes offer no practical benefit.

Consumers of your API are concerned with the methods and behaviors, not the underlying type. Instead, use the general domain name for classes, such as 'Truck', and specialize child classes with descriptive names like 'TrailerTruck'.

Explicitly naming units of measurement is another essential rule. Numeric values without units often lead to subtle bugs, especially when the intended unit is unclear. Always incorporate the unit into the variable name, such as 'delaySeconds' instead of 'delay', which could be in milliseconds, seconds, or minutes. Languages with strong type systems, like C++ or Rust, benefit from dedicated duration types like 'TimeSpan' or 'std::chrono::duration', eliminating the chance of unit-mismatch bugs at compile time. For dynamic languages, embedding the unit in the variable name ensures clarity.

Finally, be wary of the 'utils' or 'helper' classes. If you find yourself struggling to name a class, it's often a sign of a deeper architectural issue. These classes tend to accumulate unrelated functionality. Instead of creating a generic 'utils' class, refactor your code to distribute responsibilities to proper domain classes.

Break down methods that operate on a single entity into the respective class, methods that work with lists of entities into specialized collection classes, and cross-cutting concerns into dedicated classes. This refactoring eliminates the 'utils' class, resulting in a more organized and maintainable codebase.