How to name things while writing code

Naming is hard!

Did you ever struggle with naming a variable? A method? A file? ??

I am sure you have seen code examples like these:

const info = ...
function run() {...}
main.js        

This naming style is common for less experienced test automation engineers (and, who are we kidding, developers) meaning it MEANT TO HAPPEN during one of my coaching sessions:

TLDR: Some bad names were given to some variables… ??

Of course, the job of the good coach is not to give an answer (a fish ??), but to teach the person to find it themselves (teach to fish ??)! So I had to share a framework that I use for naming. And in this article, I will share it with you! ??

Is naming even a problem?

It depends on how you look at it! Often the problem with naming is that you get stuck on something and DO NOT move forward. You are trying to think hard about a “good name” but your brain goes silent… This happens because you force your brain to work too hard! ????

This method will help you split the naming into simple steps thus allowing you to:

• save time by not getting stuck on “trivial tasks” such as naming (by making the naming process asynchronous)
• reduce chances of giving a bad name AND forgetting about it (oops ??)

Framework

It is very simple! You need to follow the following sequence:

Horrible → acceptable → good → perfect

Every stage is optional. Also, you could skip any stages (aka do the math in your head and jump straight from “horrible → perfect” in one go!).

Simple, right? Let’s illustrate it with a practical example.

Example

Let’s say your goal is to create a simple program (Node.js) that "Prints out someone’s purpose"

function printPurpose(person) {
  console.log(`${person.name} will ${person.purpose}`)
}

printPurpose({
  name: "Ivan",
  purpose: "help with naming"
})        

If you run this program, it will print out the following statement:

Ivan will help with naming

And let’s say you don’t like passing an inline JSON object so you want to extract it into a variable first. How would you apply this "naming method" for the new variable?

1 - Bad name

The bad needs to be intentionally bad! Like “grammatically incorrect” bad. Let your IDE do what it was designed to do: SCREAM AT YOU!

const aaadddggggggggggggggg = {
  name: "Ivan",
  purpose: "help with naming"
}        

Why would you do that? Because SOME NAME is better than no name! But it would help if you had a reminder TO REMEMBER to fix it later.

Look, IDE spellchecker tries to help! (you are paying attention to your IDE complaints, right?.. right??!)

Let’s say you forgot to pay attention to your IDE (or wrote this code in a Notepad)… NOT ALL IS LOST! This horrible name will have a chance to be caught when:

• you add files to staging (you are looking at the diffs, right? ??)
• you open a PR
• someone reviews your code

2 - Acceptable

Ultimately, we do not want to leave the name as “aaadddggggggggggggggg”, it was a temporary solution. Let’s make it acceptable!

const data = {
  name: "Ivan",
  purpose: "help with naming"
}        

Now the problem is that this name is “technically correct”, it is data, but it is TOO GENERIC! What kind of data? Ideally, the name should reflect the content, so we need to spend more time thinking about “how to improve it”.

3 - Good

To make it good, the name should hint at its content! Maybe “personWithPurpose”?

const pesonWithPurpose = {
  name: "Ivan",
  purpose: "help with naming"
}        

So in your program, it will look like so:

function printPurpose(person) {
  console.log(`${person.name} will ${person.purpose}`)
}

printPurpose(personWithPurpose)        

Can you improve it? Most likely!

Is it good enough? Yes!

4 - Perfect

An important thing you have to know about “perfect” is that it might never happen. It doesn't have to! You might think about name for a long time… or it could be the subject of a big debate within the team. And, maybe, all this effort is not REALLY NEEDED and could be spent elsewhere?

Perfect is the enemy of the good

My advice is to timebox your naming! If you were writing code in the given scope for a few minutes and the perfect name didn’t pop into your head, JUST LEAVE IT!

IT IS PROBABLY GOOD ENOUGH! ??

Summary

To give a good name with less brain effort remember the sequence:

Horrible → acceptable → good → perfect

p.s. shout out to an amazing Erich Kuba who taught me to use this method!

The end

If you enjoyed the article don’t forget to REACT to it or COMMENT (or both). This helps the algorithm to show it to other relevant people. More people see and react means I am more motivated to write more. I write more and YOU will benefit from reading it. ????

Are you a manual tester? Or a beginner automation engineer? Want to be better? Want to learn more about test automation and not sure how to go on this journey? I can help!

I coach people on test automation within the JavaScript ecosystem. UI/API/Unit/Performance/Contracts, you name it… You can book a free first consultation to talk about your needs and goals here: https://ivanandcode.com/coaching