Aah.. naming things. A developer's favorite brain sport, nestled somewhere between attending endless meetings and refactoring code. As developers, we know that naming can be both a blessing and a curse. It's a critical part of our work, but it can lead to some hilarious but most likely frustrating names. In this post, I'll show a way we can think of variables and how you can use them effectively. Even if you feel confident naming your variables, are you also using their full potential? 🤔
A Naming Pattern to Save the Day
When you find yourself struggling to name a specific variable, function, or class, consider using the following pattern and ask yourself the corresponding questions. The pattern is [scope][typePrefix][baseName][qualifier][typeSuffix]
.
-
Scope:
- What is the visibility or accessibility of this variable? (e.g., private, public, protected, internal, package-private)
- Is this variable specific to any programming language features or conventions? (e.g., double underscore prefix in Python, dollar sign in jQuery, '@' for instance variables in Ruby)
- Is this variable part of a framework or library that requires a specific naming pattern? (e.g., Angular's 'ng' prefix for directives, React's 'use' prefix for hooks)
-
TypePrefix:
- Is this variable a boolean or a function that returns a boolean? (e.g., is, has, contains, are, integrates)
- Does the variable represent a state, condition, or action that can be described with words like "is," "has," "contains," or "integrates"? (e.g., isEnabled, hasAccess, containsItem)
- Is this a function responsible for getting, setting, fetching, or updating data? (e.g., get, set, fetch, update, retrieve, store, save)
-
BaseName:
- What is the primary purpose of this variable? (e.g., user, distance, payment, errorMessage)
- Can I describe the variable's role in the code with a clear, concise word or phrase? (e.g., registrationStatus, totalPrice, elapsedTime)
-
Qualifier:
- Are there any additional details or context that would help distinguish this variable from others with a similar purpose? (e.g., firstName, lastName, phoneNumber)
- Does the variable have specific units or properties that should be included in the name, such as "InMeters" or "InSeconds"? (e.g., distanceInMiles, timeInSeconds)
- Is there a specific state or condition that this variable represents, such as "Valid" or "Removable"? (e.g., isValidEmail, isRemovableItem)
-
TypeSuffix:
- What is the fundamental purpose or structure of this variable? (e.g., Count, Index, Sum, Average, List, Map, Array, Set, Queue)
- Can the variable's role be clarified by adding a suffix for the structure like "Count," "Index," "Sum," "Average," "List," or "Map"? (e.g., itemCount, currentIndex, totalPriceSum, ratingAverage, userList, settingsMap)
Here are 6 examples:
-
__isUserLoggedIn
:- scope: __ (Python private variable)
- typePrefix: is (boolean)
- baseName: User
- qualifier: LoggedIn
-
fetchProductById
:- scope: “” (Public methods dont have a specific prefix in most languages)
- typePrefix: fetch (function)
- baseName: Product
- qualifier: ById
-
updateEmailPreference
:- scope: “” (public)
- typePrefix: update (function)
- baseName: Email
- qualifier: Preference
-
$distanceInMetersInput
:- scope: $ (jQuery variable)
- typePrefix: “”
- baseName: distance
- qualifier: InMeters
- typeSuffix: Input
-
getUserByEmail
:- typePrefix: get (function)
- baseName: User
- qualifier: ByEmail
There may be times where you need to swap the base name and qualifier in order to give the variable a more appropriate and meaningful name. Example: getLoggedInUser instead of getUserLoggedIn.
-
getLoggedInUser
- typePrefix: get (function)
- qualifier: LoggedIn
- baseName: User
Naming Variables Effectively
Alright, so you've got a solid plan for naming variables 😎. But that's only half the battle. The other half? Comments. But not in the way you're thinking.
You might have heard the advice to scatter comments throughout your code to make it more understandable, especially for your future self. But, in reality, that's not always the best approach.
Consider this: if your code is incomprehensible without comments, then the problem isn't a lack of comments. And if your code is already clear, then you don't need the comments in the first place.
So, what's the point I'm trying to make? Use variables as comments.
When you store everything in a variable with a meaningful name, you can often understand the entire code just by reading those names and key control structures like if statements. Let me show you an example:
The other day, I came across a piece of code that took me about 10 minutes to grasp completely 🥴.
if (!row.doc[otherField]) {
let val;
if(currentField == "left") {
val = row.doc[currentField].charAt(0) === "-" ? row.doc[currentField].slice(1) : row.doc[currentField];
}
if(currentField == "right") {
val = row.doc[currentField].charAt(0) === "-" ? row.doc[currentField] : `-${row.doc[currentField]}`;
}
row.doc[otherField] = val === "-0" ? "0" : val;
row.refreshField(otherField);
}
if (currentField === "left" && row.doc["left"] && row.doc["left"].charAt(0) !== "-") {
row.doc["left"] = row.doc["left"] === "0" ? row.doc["left"] : `-${row.doc["left"]}`;
row.refreshField("left");
}
if (currentField === "right" && row.doc["right"] && row.doc["right"].charAt(0) === "-") {
row.doc["right"] = row.doc["right"].slice(1);
row.refreshField("right");
}
So let's clean it up by putting stuff into variables and giving them meaningful names:
const valueOfOtherField = row.doc[otherField];
const valueOfCurrentField = row.doc[currentField];
const valueOfLeftField = row.doc["left"];
const valueOfRightField = row.doc["right"];
const isCurrentFieldOnLeft = currentField === "left";
const isCurrentFieldOnRight = currentField === "right";
const startsWithMinusSign = (str) => str.charAt(0) === "-";
const removeMinusFromZero = (str) => str === "-0" ? "0" : str;
const ensureMinusAtStart = (str) => startsWithMinusSign(str) ? str : `-${str}`;
const removeMinusFromStart = (str) => str.replace(/^-/, "");
if (!valueOfOtherField) {
let val;
if (isCurrentFieldOnLeft) {
val = startsWithMinusSign(valueOfCurrentField) ?
removeMinusFromStart(valueOfCurrentField) :
valueOfCurrentField;
} else if (isCurrentFieldOnRight) {
val = startsWithMinusSign(valueOfCurrentField) ?
valueOfCurrentField :
ensureMinusAtStart(valueOfCurrentField);
}
row.doc[otherField] = removeMinusFromZero(val);
row.refreshField(otherField);
}
if (isCurrentFieldOnLeft && valueOfLeftField && !startsWithMinusSign(valueOfLeftField)) {
row.doc["left"] = removeMinusFromZero(ensureMinusAtStart(valueOfLeftField));
row.refreshField("left");
}
if (isCurrentFieldOnRight && valueOfRightField && startsWithMinusSign(valueOfRightField)) {
row.doc["right"] = removeMinusFromStart(valueOfRightField);
row.refreshField("right");
}
With this change, the code reads almost like plain English. However, upon closer inspection, we can identify some unnecessary logic steps that can be removed and simplified. Take this line, for example:
val = startsWithMinusSign(valueOfCurrentField) ?
valueOfCurrentField :
ensureMinusAtStart(valueOfCurrentField);
Logically, it can be further simplified. If the value starts with a minus sign, we keep it; otherwise, we add a new minus sign. Essentially, this means we can simply add a minus sign at the beginning. So, the line can be simplified to:
val = ensureMinusAtStart(valueOfCurrentField);
Assuming the performance of row.refreshField
is negligible, the same logic can be applied to the if statements by removing the && startsWithMinusSign(valueOfRightField)
and && !startsWithMinusSign(valueOfLeftField)
conditions. The entire code should now look like this:
const valueOfOtherField = row.doc[otherField];
const valueOfCurrentField = row.doc[currentField];
const valueOfLeftField = row.doc["left"];
const valueOfRightField = row.doc["right"];
const isCurrentFieldOnLeft = currentField === "left";
const isCurrentFieldOnRight = currentField === "right";
const startsWithMinusSign = (str) => str.charAt(0) === "-";
const removeMinusFromZero = (str) => str === "-0" ? "0" : str;
const ensureMinusAtStart = (str) => removeMinusFromZero(
startsWithMinusSign(str) ? str : `-${str}`
);
const removeMinusFromStart = (str) => str.replace(/^-/, "");
if (!valueOfOtherField) {
// If the current input field is on the left, let's remove the minus from the start
// and if its on the right, let's add the minus at the start. And put it into the
// other field. (NOTE: In the original code there were exactly two fields, left and right.)
const newValue = isCurrentFieldOnLeft ?
removeMinusFromStart(valueOfCurrentField) :
ensureMinusAtStart(valueOfCurrentField);
row.doc[otherField] = newValue;
row.refreshField(otherField);
}
// If the current field is the left one and there is an inputted value then
// make sure to add the minus at the start
if (isCurrentFieldOnLeft && valueOfLeftField) {
row.doc["left"] = ensureMinusAtStart(valueOfLeftField);
row.refreshField("left");
}
// If the current field is the right one and there is an inputted value then
// make sure to remove the minus from the start
if (isCurrentFieldOnRight && valueOfRightField) {
row.doc["right"] = removeMinusFromStart(valueOfRightField);
row.refreshField("right");
}
At this point, we can easily read through the code without tearing our hair out. The code accomplishes two main tasks:
- It ensures that when the user enters values in the left and right fields, the right one will always be positive, and the left one will be negative.
- If one of the fields hasn't been filled in yet, the code copies the value of the current input field to the other field.
Understanding this behavior with the original code would have been quite challenging. However, by using variables more effectively, we can abstract away the complicated syntax mess and make the code read more naturally 💪.
Let me know what you think in the comments. Maybe you have some more suggestions. If you found this post helpful, consider liking it and following for more posts in the future. Your support means a lot and encourages me to keep sharing more ❤. Happy coding!
Top comments (23)
I think
ensureMinusAtStart
would be a clearer name for the conditional version ofaddMinusAtStart
.You're right! I wasn't sure if "ensure" was clear enough but hearing it from an independent source.. imma change it 👍
ensureMinusAtStart()
is semantically correct if you are doing that, i.e. if you are adding a minus only if there is not one already there. In the case of:I would be inclined to retain an
addMinusAtStart()
function such that you have something like this (C++ kind of thing) :Just a thought though.
having learned more about the importance of idempotency (aka desired state pattern) in (distributed) information systems, I use "ensure" all the time now. For example instead of delete(x), we might even write ensureDoesntExist(x).
You need to review your use of
if (!valueOfOtherField)
if you're targeting clarity. There's no evidence in your code thatvalueOfOtherField
is a boolean type, but (based on C-type-derived languages) the!
operator takes a boolean as input and produces a boolean output.It looks like you're relying on either an overload of the boolean
!
operator, or an implicit cast ofvalueOfOtherField
to a boolean type. Either case is not clear. I have no idea of the type returned byrow.doc[otherField]
so I would hope that a conditional that used that returned value would be a proper value comparison retuning a boolean (e.g., where the return type us a string,if (valueOfOtherField.isEmpty())
.Naming event listeners in particular, which can be asynchronously managed and therefore trickier to debug within context, is a great exercise. "on[Before|After][state][change]" is a good template here.
Great, haven't thought of that one 👍 Thanks for sharing
Good references/examples in the careful thought put into the VS Code extensions API:
vscode-docs.readthedocs.io/en/stab...
German "Gründlichkeit" at its finest. Very good!
Using logical scheme-based, objective descriptions saves lots of time and effort all around. This is especially helpful in large or long-lived projects, but, honestly, once you get used to naming things like this, you wouldn't have it any other way even in small one-off personal projects, either.
Love the intro, more true words were never spoken xD
how to name a array which will hold two different data let say town data and city data based on condition.
I have named it cityTownData is there any better way to do that
I did something similar a few weeks ago and needed to change it back. If you can, make them two seperate arrays as this becomes easier to scale and work with in the future. But if not, you could name it cityAndTownData to avoid confusion that "city" is just a descriptor for "town" and "cityTown" is one thing. The condition you can add at the end like this:
cityAndTownDataWithLargePopulation
or even bettercityAndTownArrayWithLargePopulation
orcitiesAndTownsWithLargePopulation
. "data" is too general and could be anything, so replacing it with "array" you give developers a better idea of the type. So final answer would be:citiesAndTownsWithLargePopulation
as it will be either city or town data so can i make it cityOrTownArray or should i keep them seprate ?
Don't overengineer your variables and spend too much time thinking about one. The core purpose of good naming is so your code can be easily read by others and yourself without feeling stupid. If you feel stupid reading other peoples code its most likely their fault. Just check your entire function and ask yourself the question. Is the code as a whole clear and understandable? If yes youre fine.
PS: If cities and towns are two different things in your code, seperate them. If they are pretty much the same, just use one word, or a generalization word like "settlement".
ठीक है
This post inspired our weekly #DEVDiscuss! Check it out and join the convo:
#DEVDiscuss: Naming Things
Erin Bensinger for The DEV Team ・ Apr 25 ・ 1 min read
Great article of a fundamental subject.
This certainly makes sense to me. Naming is hard and having this pattern as a guide is really useful.
Excellent points raised!