Do's And Don'ts For Naming Software Components

Source code has two main purposes: The first, and more obvious one, is to specify the behavior of a computer program, describing precisely how the software must behave to achieve some intended purpose. The second, often not prioritized, is to communicate with other programmers, (hopefully) creating an understandable record of how the problem at hand is being solved.

By investing the time to make the source code not only correct, but also clear, it enables others to jump in, understand it, and make modification as needed. In a company, software needs to constantly change and adapt while surviving various changes, including even of who the programmers working on the code are.

Ultimately, for a piece of code to have a longer-lasting effect, it must be intelligible for the next person tasked with maintaining it and keeping it running -- and that person might even be yourself, when you have long forgotten about all the original details. For this goal, good naming, such as for classes, methods and variables, is the vital first step.

DO's

DO Use Names From the Problem-Domain

Software exists to fulfill some task external to itself, so use the words that represent the concepts of the problem being tackled.

For example, if you are writing a JSON parser, use the same words from the spec: “Element”, “Object”, “Array”, “String”, “Number”, and so on. If you are working on a school management system, use the words that the stakeholders employ: “Student”, “Class”, “Grade”, “Attendance”, “Lecturer”, “Legal Guardian”, and so on.

Adjustments of existing functionality and future demands will be expressed using the words that the stakeholders understand and employ, so it makes sense to keep the mapping from “business requirements” to “source code” as plain and direct as possible.

DO Use Words For Technical Patterns

You are also communicating with fellow programmers, and words such as “Model”, “View”, “Tree”, “Node”, “Flag” convey specialized knowledge very efficiently. Leverage them whenever it improves communication and helps describe the purpose of the piece of code.

For example, a class named UserModel conveys the idea that this is the piece of code which describes the attributes of an user and most likely doens't contain business logic or a description of how it should be displayed on the screen. The class named AttendanceView most likely describes how an attendance sheet should be displayed on the screen, with minimal business logic included. Another class named ImageLoadedObserver most likely registers a listener which is triggered when an image finished loading, implementing the “Observer” design pattern.

DO Ensure Every Word is Needed

Names should be short and concise, so consider the removal of each word at a time and reflect whether the resulting name still retains the intended meaning. Each word should play a role in the conveyed idea, and taking them out is a good exercise to test this is actually the case.

Consider a service named CustomerOrderDataManagementService. Since, by definition, every order must be placed by a customer -- placing an order makes you a customer --, we can drop Customer from the name. Most software services deal with data anyway, so we can also drop Data. ManagementService is also a mouthful, and Manager conveys pretty much the same idea, and we've arrived at OrderManager as the more concise name of the service.

DON'Ts

DON'T Require An Explanation

If the chosen name requires an explanation, it has already failed. The purpose of a name is to convey meaning and ease communication, so if it requires further clarification, it is not self-evident what it is about and it has not fulfilled its goal.

Consider the following names:

• DataService - “Q: It handles data of what exactly?” “A: So...”
• PBOSManager - “Q: What is PBOS?”. “A: It stands for our Proprietary...”
• Ariadne - “Q: What does this part of the code do?”. “A: Well, from the Greek mythology...”.
• TaskTimeout - “Q: What is the unit of measurement? Seconds, Milliseconds...”. “A: Well you actually provide a suffix such as...”

DON'T Lean Too Much On Empty Words

Words such as: “data”, “value”, “result”, “output”, “helper”, “util”, “system”, “service” do not convey any meaning by themselves, so avoid them in wider scopes. For small functions, naming a variable “data” is just fine, as it should be clear from context where the data came from and where it's going. For the wider system scope, though, it's likely not the only piece of data flowing, so we should be more specific.

DON'T Overuse Acronyms And Abbreviation

Acronyms that are adopted and well-known industry-wide, such as “HTTP”, “XML”, “JSON”, makes communication simpler and are preferable to using all the words they stand for. Other than that, acronyms fail to provide any clue to what they mean and create a barrier to understanding.

Less-known and project-specific acronyms should be avoided. Let the usability test be whether the web search “define $ACRONYM” returns the exact meaning of the acronym.

Abbreviation for overly long words can be helpful, but can also introduce ambiguity. The classical example is using “Auth”, while actually “Authorization” and “Authentication” are two different concerns.

By and large, with modern IDEs providing powerful auto-completion, large computer screens, and negligible storage costs for text files, there's currently no excuse to use short cryptic names compromising understandability.