I'm a software engineer working as a full-stack developer using JavaScript, Node.js, and React. I write about my experiences in tech, tutorials, and share helpful hints.
My general rule is to "call it what it is." What I mean by that is to pretend another developer came to you to ask about a variable, function, or class that you have knowledge about. I think that most people would provide a good explanation. That explanation should be fairly close to the name. Other developers should not have to do detective work or ask what something means, make it apparent.
Some examples:
"It gets the user." - getUser()
"It stores the number of milliseconds that have passed." - elapsedTimeInMilliseconds
"It compares data from flights." - compareFlights()
"It calculates the amount of fuel used in a flight." - calculateFlightFuelUsage()
"It stores the size of the fuel tank in liters" - sizeOfFuelTankInLiters
I think that is usually enough to have a good name. In development, there seems to be this compulsive need to have short "concise" variable names. I think the word "concise" is misused to mean "short and obvious to me, writing the code at this moment." But it really should mean "short, accurate, and complete." In an example of var d; vs. var elapsedTimeInDays;, I think defenders of d would say that you can use the context of how it is used and deduce that it means "days". The problem is that I have to look further and see what is actually being stored when I shouldn't have to. Another issue is when that code is updated in the future. If the next developer has to add another "days" variable in that scope, guess what it will be named? d2. It is wishful thinking to assume that it will be refactored and named properly when the time comes. Finding a good middle ground and being concise (for real) is important. Use enough words to accurately and completely describe something. If it happens to be a little longer, no big deal, we have auto-complete.
Beyond that, I have some "do not" rules and general guidelines that I try to follow.
No prefixes (also known as Hungarian notation). Name it so that a prefix is not needed and it is more human-readable. Example: isActive instead of bActive. Using it is easier to read, in my opinion. if (isActive) translates easily to "if it is active."
Limit abbreviations and acronyms. Commonly used ones in the field are okay (like "URL" or "API") but do not create new ones. Learning a codebase is difficult enough for newcomers, introducing specific acronyms that developers have to ask about and remember makes it that much more difficult for everyone on the team. There are acronyms I use at work on a weekly basis, but I have no idea what they mean or their origin.
Variables are usually nouns, classes are usually singular nouns, and functions are usually verbs.
These types of discussions can seem nitpicky and spark negative emotions if brought up in a code review, but it is important to look at any suggestions holistically. One var d; in the code is not the end of the world, it will not ruin code quality. But multiple developers across multiple years consistently using not so great names becomes a problem. Will it be understood by you a few years later? Will it be understood by a developer that starts this job tomorrow?
My general rule is to "call it what it is." What I mean by that is to pretend another developer came to you to ask about a variable, function, or class that you have knowledge about. I think that most people would provide a good explanation. That explanation should be fairly close to the name. Other developers should not have to do detective work or ask what something means, make it apparent.
Some examples:
"It gets the user." -
getUser()"It stores the number of milliseconds that have passed." -
elapsedTimeInMilliseconds"It compares data from flights." -
compareFlights()"It calculates the amount of fuel used in a flight." -
calculateFlightFuelUsage()"It stores the size of the fuel tank in liters" -
sizeOfFuelTankInLitersI think that is usually enough to have a good name. In development, there seems to be this compulsive need to have short "concise" variable names. I think the word "concise" is misused to mean "short and obvious to me, writing the code at this moment." But it really should mean "short, accurate, and complete." In an example of
var d;vs.var elapsedTimeInDays;, I think defenders ofdwould say that you can use the context of how it is used and deduce that it means "days". The problem is that I have to look further and see what is actually being stored when I shouldn't have to. Another issue is when that code is updated in the future. If the next developer has to add another "days" variable in that scope, guess what it will be named?d2. It is wishful thinking to assume that it will be refactored and named properly when the time comes. Finding a good middle ground and being concise (for real) is important. Use enough words to accurately and completely describe something. If it happens to be a little longer, no big deal, we have auto-complete.Beyond that, I have some "do not" rules and general guidelines that I try to follow.
isActiveinstead ofbActive. Using it is easier to read, in my opinion.if (isActive)translates easily to "if it is active."These types of discussions can seem nitpicky and spark negative emotions if brought up in a code review, but it is important to look at any suggestions holistically. One
var d;in the code is not the end of the world, it will not ruin code quality. But multiple developers across multiple years consistently using not so great names becomes a problem. Will it be understood by you a few years later? Will it be understood by a developer that starts this job tomorrow?Yup