Naming things properly when writing code may be one of the most important aspects of improving oneself as a coder, but it is often disregarded by beginners or experienced coders alike. Naming things is usually rushed (“it’s a waste of time”).
Naming things refers to giving names to code or data abstractions such as:
- Variable names.
- Function names.
- Class names.
- Data Tables, Collection or relation names.
- Any other abstraction that will be referenced in another part of the program (eg: properties, enum, keys,…)
Naming things as a software engineer goes actually way further than code itself:
- Packages, Files, Projects name, Repository names.
- Server instances, Images names.
- API endpoints, Jenkins jobs names, etc.
Naming things improperly and how it affects productivity is beyond software design (eg: company design), but we’ll focus only on software development in this article.
Why is naming things so important?
- Self-explanatory code. Names reduce the need for extensive comments and documentation.
- Planning. Names provide and understanding of how the system works as a whole, and of future intents of the developer.
- Improved software design. The act of naming things properly helps to achieve a better software design by clarifying one’s state of mind.
- Increase productivity for the team.
“Writing code is a lot easier than reading code”.
This fact holds true wether you work as a team, or you go back to your own codebase in a few weeks without looking at it.
By choosing names you are mapping human-language with machine-language, but more importantly, you are also translating a concept or an idea into a medium readable by yourself and others, which is readable text.
The good news is, it only takes a bit of will to improve your “naming skill”.
You will also quickly recognize when names are poorly chosen, often a red flag for bad software design, or “selfish coding”. Either one could trigger a code refactor or a pull-request rejection.
How to name things properly
Naming things properly depends of the context (eg: system, language, team, project, domain, etc.). Below are some general guidelines and examples.
Names in general
- Should be meaningful within their context.
- Short-and-Descriptive rather than Long-and-Descriptive names.
- Should reveal intention.
- Naming must be consistent (eg : create a naming convention for the team).
Meaningful within their context
- Names help understand the logic. They need to be distinguishable.
total = price * quantity
total2 = total * tax_rate
total3 = account_credit + coupon_valueif (total3 < total2) { // Completely unclear what we are comparing
processOrder()
}
// Bad naming
- Any variable that relies on a numeral to distinguish it from a similar
variable needs to be refactored.
payable_total = price * quantity * tax_rate
available_funds = account_funds + coupon_valueif (available_amount < payable_total) {
// Clear, and we've even spotted a mistake in this comparison.
processOrder()
}
// Better naming
- Find a precise name. It sometimes requires some vocabulary research, but it’s investment well worth making in my opinion.
var total2 // Very bad, don't do this.
var amount_total // Mmmh.
var order_total_with_tax // Eh, a bit too long.
var payable_total // Yes, finally clear!- Avoid words that don’t add any value.
let data = await readGoogleReverseGeocodeApi(location)
// Bad. We know there is "data" in a variable! "data" is probably one of the worse variable name possible anywhere.let addressObj = await GoogleAPI.getReverseGeocode(location)
// Better
Intention revealing
- Make apparent the intention of variable or function (when there is one).
Example for a boolean variable:
var empty = true
// Badvar isEmpty = true
// Ok, it is now obvious that the variable is a boolean.
Example for a function:
function isEnabled() { return boolean }
// Good, it is obvious that the function purpose is to return a boolean.class User {
...
updateUserInfo (name) {
this.name = name
}
// Bad, unnecessary long function name and vague.setName (name) {
this.name = name
}
// Ok, short and descriptive.
// user.setName(name) versus user.updateUserInfo(name)
Use simple words when possible
- Simple words are usually easier to memorize and understand (as opposed to acronyms for example). If name conflict arise, it is usually because the code is not modularized enough.
<RITE type='text' defaultValue='20' />
// What is the RITE acronym stands for? (React-Inline-Text-Editor)<Editor type='text' defaultValue='20' />
// OK, pretty self-explanatory.
I might be biased as I highly dislike acronyms in general. When having a choice, I prefer a simple pronounceable word instead of complex one.
Use case styles consistently
Case styles are used as a convention to quickly recognize different programming types.
Special case styles types are:
- camelCase, CamelCase (eg : iPhone, FedEx)
- snake_case (eg : car_speed)
- kebab-case (eg : game-level)
In Javascript, as an example:
// Constants are usually in SNAKE_CASE.
const COOKIE_MAX_AGE = 30
const ITEM_PER_PAGE = 4// Variables are usually in camelCase.
let jsonFile// Class are usually CamelCase.
class Layout { ... }
Wether to use underscore or camelcase or something else is often a personal or team choice. The important part is to be consistent.
aRatherLongNamea_rather_long_name// Which one is easier to read?
Short or long names ?
It depends.
- Variables with short lifetimes or short scope should be named shortly (eg: loop counter can be a single letter. Local variables can be single words. Globals should usually be more elaborate).
for (let r of rows) { ... }
// OK. One letter variable "r" is fine the loop here.function getCoordinates (lat, long) { }
// OK. "lat" in this function context refers clearly enough to "latitude".
- However removing few letters from a word just to shorten a name is generally not a good idea.
UpdatePriceCr.start()
// Bad, removing 2 letters of the word Cron (Cr) unnecessarily makes it less descriptive.var ag = new Agenda()
ag.sch(time)
// Bad, removing 4 letters of the word schedule (sch) unnecessarily makes it less descriptive.
- Which one is better?
// naming A
let dR
let dCV
let dK
let dDin// naming B
let radius
let curvature
let conic_constant
let inner_aperture
It is a tricky question.
These variables seems to be used in an optical physics context, where math formulas will be calculated. Someone familiar with optics may immediately recognize what dR or dCV stands for, especially if it is common abbreviations in physics books. This is the specific situation where short abbreviations are OK or even better, as they allow direct comparison with textbook formulas.
Still confused on how to name things?
Just ask yourself as a training exercise, and even if it is a throw-away code snippet (which by the way often survive longer than expected) :
“In 2 years, will I read these lines and quickly understand what’s going on or will it be an archaeological dig?”
If the answer is No, then spend a minute or two trying to come up with a better naming. Don’t give up.
- How can I help someone else to quickly understand my code?
- Is there a word that has a better meaning / that is simpler / that is more precise.
- Are names looking consistent? Can I rename few things to decrease confusion?
This thinking habit can improve your code quality and your abstraction skills.
References and additional information.
- Wiki C2 : Good Variable Names
- Stack-exchange : Is there an excuse for short variable names
- Oreilly.com : The worlds two worst variable
