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:
Pascal case: TriangleArea
Camel case triangleArea
Snake case: triangle_area
Kebab (or Train) case: triangle-area
Classes, interfaces, and methods
Chapters can be dedicated to rules for naming classes, interfaces, and methods. But, generally:
Classes are nouns
Interfaces are adjectives
Methods are operations
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:
Employee - The obvious choice for the class representing the domain object.
EmployeeController - The top-level entry point for a REST application that generally just delegates to a single service to handle operations on a single type of resource. It handles errors and returns the appropriate HTTP response code.
EmployeeService - A service that implements the logic of a Controller. It generally delegates to and coordinates the operations of other services and perhaps an EmployeeClient or EmployeeDAO. It should have no direct external dependencies.
EmployeeClient - A class that calls out to a single remote service to perform operations on an Employee.
EmployeDAO - A class that reads/writes Employees from/to a data store. Typically called only from the EmployeeService.
EmployeDTO - A data-only class used to transfer the data for the Employee to/from EmployeeDAO or DataClient and to/from EmployeeService
<xxx>Util - A utility class that collects related miscellaneous operations. E.g. PrintUtil
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.
Rename variable or method
Create variable for expression
Extract code into its own method
Use them