Clamberry Blog

Reflections on a career in software development (and, maybe, other sun-dried thoughts)

 

What's In A Name?

Posted on Oct. 28, 2022

Code is how we tell our colleagues how we feel about them.
- Venkat Subramaniam

It should seem like an obvious cliché, but meaningful names for classes, methods and variables are crucial for a literate style of programming. But too often I've heard programmers say something like "I'm terrible at naming variables".  Names are crucial and should reflect the careful thought process gone into crafting code rather than the after-thought or no-thought they too often convey.

Much has been said on this topic. And this article does not offer any groundbreaking new ideas. Rather, I've collected some guidelines I've used or at least tried to consider in my years as a programmer.

This topic. i.e. "naming", is only one aspect of the larger topic of literate programming. I encourage you to explore those ideas further. See http://literateprogramming.com/ 

Variable Names

Don't be afraid of long names

Long gone are the days of languages that impose length restrictions. In the early days, many languages restricted variables to just 2-6 characters.   Now, there's no excuse for such brevity. I recall a programmer who had to work with that restriction moving to a new language that liberated him from it. His variable names went from 6 characters to complete sentences. That may have been extreme. But the sentiment was solid. His code may have been a bit verbose but you never had to ask the purpose of a variable.

Abbreviated or condensed names are a good compromise.

Rather than a name like "max", consider "maxNumberOfEmployeesPerDepartment" or "maxNumEmpsPerDept". 

Name variables by their role or purpose, not their type

Too many times, I've seen variables with names like "personObj" for an instance of a Person class. Instead, it is much more helpful to use a name that connotes why or how this person is being used or what the person represents. And adding "Obj" to the variable name does not really add any information at all.

Instead of "personObj", consider a name like "employee" or "supervisor" to connote the person's roie. Of course, Employee and Supervisor could also be class names if they have sufficiently different behaviors in your application. But I hope you get the idea.

An exception to this guideline might be for loop counters like “i” where the meaning should be obvious. 

Use variable names to convey the meaning of a complex expression

"But I'm only using it once." is a line I've often heard. A complex expression may have an obvious meaning to you. But someone reading your code shouldn't have to stop and distill that meaning. 

So, instead of a statement with an expression that uses a term like "base*height/2", extract that term into its own variable:

triangleArea = base*height/2

Then, use triangleArea in the statement. 


Follow the style conventions of your language

Every language has its own convention for naming variables composed of multiple words. Ignore your own preference and use the convention of the language you are using. The standard conventions are:

Classes, interfaces, and methods

Chapters can be dedicated to rules for naming classes, interfaces, and methods. But, generally:

Impl or "I" class names for interfaces

 A common scheme is to name an interface something like EmployeeService and the implementation class something like EmployeeServiceImpl or IEmployeeService. 

This convention is the theme of many code and language wars. I will neither condone nor condemn it. But my preference is to avoid it. Ideally, if you have an interface, there would be multiple implementations. The 'impl' convention does not scale beyond a single implementation.

Rather than use "Impl" tacked onto the end of the interface name, consider a qualifying prefix that describes the implementation.

A classic example is an interface named "Listener" with classes named "EmployeeChangeListener"

Class and Interface Names For Application Layers

Classes are generally organized into packages that connote their role in an application. Their names should reflect that. E.g. for an Employee resource in a web application:

Methods

Good style demands that methods be cohesive, i.e. they should do one and only one thing.  They should be given names that make that purpose clear 

Divide and Conquer 

 As for complex expressions, split long methods into multiple operations that are meaningfully named and cohesive. Compose complex methods by delegating to those methods.

Avoid redundant comments above a complex expression or method

It may seem like heresy, but avoid comments that serve only to explain a variable's or method's purpose. Use names to convey that meaning. Instead, comments should be reserved for implementation details, context, or similar detailed application-specific information.

Refactoring Tools

Many IDEs have built-in support for these type of refactorings. E.g.

Use them


References: