Naming is critical to software development because it directly affects the readability and therefore how easy code is to understand; code that is easy to read and understand is easier to change.
Initial Development
Considering changes in the initial development phase might seem irrelevant because it is tempting to assume that initial development of a system only involves writing new code. This, however, is very rarely the case, the code is revisited, modified, updated and/or refactored as development proceeds. Code that is harder read causes the rate of change to decrease over the lifetime of the application.
Now consider what change means in the maintenance phase. Most systems have longer than anticipated life spans and need ongoing maintenance, in the form of bug fixes and adjustments to meet new business requirements, during the course of their life. The act of maintenance means code changes, thus the easier it is to change the code the quicker and cheaper it is to maintain.
At TDD Buddy we advocate for 4 stages of naming: meaningless, specific/general and meaningful; while
others advocate for up to 7 stages.
The specific/general stage wraps the meaningful stage. This is to
express the tug of war that often occurs between the specific and general when trying to get to the
meaningful stage.
This is because the process is emergent. Things can start at any point and move in any direction. For example, you can have a meaningless name that is changed to be specific or general, or you can have a meaningful name that is changed to be meaningless.
It would be awesome to have the ability to immediately naming things at the “Meaningful” stage. Unfortunately, that is often not the case. Most likely you will start at the meaningless or specific stage rolling the concept around for a bit before arriving at a meaningful name.
Figure 1: Stages of naming
It is important to be aware of how well concepts are named so that you can strive to push concept names to being more meaningful. The key here is continuously improving concept names as your work.
Don’t spend too much energy on coming up with a meaningful name right at the beginning, this is wasted energy, pick a name based on the information you have, identify what stage it is in, and revisit the name every time you read or modify that section of code. If you have a better name for it then update it, otherwise leave it. If you must leave that section of code and don’t have meaningful names yet, leave todo comments to improve the names later.
Meaningless
No references to technical or domain concepts
Examples:
- var x;
- private bool IsFooGood()
- No reference to technical or domain concepts
- Very hard to change because you are not quite sure what it does
- Very high chance of duplication of the concept
- Very hard to delete because you are not quite sure what it does
Specific
References technical concepts or very specific domain examples
Examples:
- var repositoryForHandlingLineItemsForCustomerX;
- private bool AreCustomerXLineItemsNullOrEmpty()
- References technical concepts, very specific domain examples
- Hard to change
- Hard to delete
- High chance of duplication
Meaningful
References domain concepts. The ideal state of naming!
Examples:
- var ItemCatalogue;
- private bool CatalogueIsEmpty()
- References domain concepts with references to technical concepts where necessary
- Easy to change
- Lower chance of duplication
- Easy to delete
General
References very generic terms with little meaning in the domain
Examples:
- var repository;
- private bool AreItemsNullOrEmpty ()
- Very generalized ideas with little meaning in the domain
- Hard to change
- High chance of duplication
- Hard to delete