What does this ‘x’ mean?

In my early days as an Electronic engineering student, I started to create small algorithms in C++ to solve these little things, such as calculate the area of a triangle. Here’s a very simple piece of code:

void main() {
    x=10;
    y=20;
    z=a*b/2;
    cout<<c;
}

At that very moment, as someone who is always worried about communication, I thought, what about this version?

void main() {
    base=10;
    height=20;
    area=base*height/2;
    cout<<area;
}

It sounded better in my head, but I saw everyone using single letters. I was so influenced by math and physics formulas, and I thought it was just a waste of time and space. So in the next years programming with Assembly, C,HDL, Matlab… I didn’t care about naming variables at all. I also worked in really advanced topics like voice recognition, multivariable control, robotics, path planning, and my variables remained with the same pattern(a, b, v1, v2). It wasn’t a big deal, at the end of the day, these were just class projects, no one in the world would use them in the future.

One day, I thought I was missing some knowledge of software engineering, I wanted to get some skills to be a better programmer. A little research led me to the book Clean Code by Robert C. Martin. It was just a hobby, I didn’t want to become a software developer, I was ‘happy’ with my electronic stuff. I remember I got a PDF (sorry, that was a hard time), and downloaded it to my smartphone, and I started to read in my free time (a lot of free time). With great surprise I learned my very first great lesson about naming variables. To be honest, at the moment I just liked that the author was aligned with my early thoughts about variables.

The author wrote about something called readability (meh). I just trusted him and kept reading. I was impressed about these longer names, my initial idea wasn’t quite as generous with meaningful names, however in this case he proposed something like the following the example:

void main() {
    baseInCm = 10;
    heightInCm = 20;
    triangleAreaInCm2 = (baseInCm * heightInCm) / 2;
    cout << triangleAreaInCm2;
}

It was kind of a WTF moment. But I was ok because I’m quite talkative, so it was like unlocking a fear. The fear of talking too much while programming. So I felt a little bit excited. And more when I talked about naming functions and classes.

The more I read the more I felt I should have been a software engineer from the very beginning, but there was no time for regret. This piece of advice, that seems simple, was a game changer. I could express my process of thinking in an algorithm in the same program.

Years later I started to study python. I created an application for the accounting of a friend’s small business, obviously, using beautiful meaningful names for variables, functions and classes. I did the work for free. And left it.

That was ok. I felt better. But just that. Nothing as impactful. And then the second milestone got here and I definitely fell in love with naming things. At the beginning it was hard, frustrating. Yes, I started to work with legacy code in a company and I was in charge of the maintenance of a very interesting app from the customer perspective. Tons of lines of code (in the same file), and guess what?. The variable’s names were like “val1”, “val2”, “df1”, “df1_copy”, “def save()” or “def get()”. So yes, as you can imagine there were two challenges: understanding the algorithm and scrolling through several times to remember what this “val1” var means, or what the heck they were saving or getting. So I finally understood why readability matters.

During this experience I used a great part of my available (and precious) time trying to figure out the meaning of the variables and functions. It was really hard to debug and maintain this code. And the clients were really demanding so I had to hurry up, and there wasn’t AI assistance or even documentation. At the beginning, I was a little bit cautious. I didn’t want to touch anything or break something, so against my will (I was more worried about paying the rent than code quality) I solved a couple of bugs (created another ones) and added some new features without changing the names. As I got more confident I started to change some names, but they couldn’t give me more time to improve this. So months later I couldn’t handle it, and I quit (I’m really into it). I felt that I was becoming less smart by reading this code everyday. So I decided to become what I call an “Entity Naming Professional”.

Great! Hopefully you’re still reading and motivated, maybe convinced that giving appropriate names to entities is not only cool but necessary, perhaps the most important thing to do in order to make our code readable enough. Therefore, I’m going to share with you my guide to name things when coding.

Side note: I want to encourage you to read the Clean Code book to know more on naming things, the following is a practical guide to help you to find good names, maybe unlock your creativity. Furthermore, I have to warn you that I’m kind of pythonic so you can see these underscores everywhere, you can use camel case, or your preferred one.

1. Naming variables or class properties:

From here, it is clear to you that “var1” or “val1” are not options so this is the moment to express yourself. A variable is space in memory we use to hold some information while performing a process, maybe these names are simpler to create, I’m going to mention multiple types of variables and my personal advice:

1.1. Booleans and flags:

I used to name these variables as questions. This helped me to know exactly the value it enclosed:

has_permission
isAdminUser

So when using if clauses it sounds more natural to read:

if has_permission or is_admin_user:

1.2. Data types:

Although, in strongly typed programming languages or even python annotations we are specifying language-related data types, it could be helpful to add some more human readable type in the name:

error_text
wordsValue
discountPercentage
config_path
customersApiUrl
databaseConnectionString

1.3. Collections

If we want to store a list of elements in an array (or the result of a function), the name of the variable should include the fact to be a list or an array (etc):

user_list
usersArray

You may ask, why not just the plural (users), because you are indicating the data type you’re using in the collection. In Python for example, we can have collections as dictionaries, lists, tuples, sets, numpy.array, pandas.dataframes that have different implications.

1.4. Counters

Avoid using the “i” or any other contraction in loops. I know we’re so accustomed to this but you can use “-index”, or in case of Python’s for or forEach loops in javascript is better to use the name of the singular entity:

for index, num in enumerate(num_list):
for user in user_list:
userList.forEach( user => {})

What’s the matter? As the procedure within the loop grows, these counters become a “normal” variable so its name has to be meaningful just like any other variable.

1.5. UI elements:

Question, what does the html element ID “nextPage” mean to you? And what about “customerName”? If you didn’t notice the ambiguity, think about these IDs:

nextPageButton - nextPageButtonDiv
customerNameLabel - customerNameInput

It’s quite important to specify the type of the element, mostly if we’re going to manipulate them using javascript.

On the other hand, I like to be aware about html classes names to be meaningful, and separate the selector classes using a prefix like “js__user-link”.

1.6. Database and dataclasses fields:

Again descriptive names and also you can use the measurement unit, and please full names of foreign keys:

discount_amount
product_id
Is_active

2. Naming functions

Naming functions appropriately has two benefits: improve the readability and help us to identify when we need to refactor, increasing the reusability. This one is simple, just answer the question: what does the function do?

test_the_api_can_create_user()
checkIfUserIsAdmin

Here are two special considerations:

2.1. Naming data-related functions

If the function is executing a query I use the SQL verbs (select, delete, update, insert):

select_user_by_id()
updateUser()
insert_customer()
deleteProduct()

If the function is not executing a query or connected to a database, but is performing some data related operation, I use verbs like get, create, edit, remove.

get_user_by_id() or fetch_user_by_id() 
edit_user()
createCustomer()
remove_product()

This is important because some functions like controllers may be performing different operations before or after executing the database query or don’t even require a database connection. So I can easily know if the operation is related directly with the database.

If the function is a class method we can shorten the name if the object class already contains relevant information for example:

User_service = UserService()
user_service.get_by_id()

2.2. Using naming to refactor

Now, I talked about refactoring. Let’s see when this happens. Let’s suppose I have this piece of code:

def function1(strings, x): 

    strings2 = [] 

    for s in strings: 
    s = s.strip() 
    s = re.sub(r'\s+', ' ', s) 

    res = "" 

    for s in strings2: 
    res += f'<p>{s}</p>'

    with open(x, 'w', encoding='utf-8') as f: 
        f.write(res, ‘x’)

Good, we can easily discover that this function is receiving a list of strings, they are cleaning the strings, and then merging them as html text using paragraphs, and finally it’s saving a file with the generated html content. Isn’t it?. If you have some experience with Python you know that we can use list comprehensions, or join, but I’m trying to generalize the algorithm. So let’s improve it by using better names:

def save_cleaned_and_merged_strings_as_html_paragraps_in_file(
    html_file_path, string_list
):
    cleaned_string_list = [] 
    
    for string in string_list: 
    string = string.strip() 
    string = re.sub(r'\s+', ' ', string) 

    html_content = "" 
    for cleaned_string in cleaned_string_list: 
    html_content += f'<p>{cleaned_string}</p>'

    with open(html_file_path, 'w', encoding='utf-8') as html_file_object: 
        html_file_object.write(html_content)

That’s way better, but something is off (OK, I went a little bit further). The name of the function could be a little hard to read or use. What usually happens is that when the name of the function (or the class) is so long it’s highly probable that the function is doing too much, so applying the principle of single responsibility we get:

def clean_string(string):
    cleaned_string = string.strip() 
    cleaned_string = re.sub(r'\s+', ' ', cleaned_string) 
    return cleaned_string


def generate_html_content(string_list)
    html_content = "" 
    
    for cleaned_string in cleaned_string_list: 
        html_content += f'<p>{cleaned_string}</p>'
    
    return html_content


def save_file(file_path, content):
    with open(file_path, 'w', encoding='utf-8') as file_object: 
        html_file_object.write(html_content) 


def create_html_file(html_file_path, string_list):
    
    cleaned_string_list = [clean_string(string) for string in string_list]
    html_content = generate_html_content(cleaned_string_list)
    save_file(html_file_path, html_content)

And that’s it. A beautiful, well-named and reusable set of functions, easy to read and maintain.

3. Naming Classes

If we want to try OOP we’re going to need to create classes. The good thing about naming classes is that you can realize whether or not you’re going to need to use OOP. Isn’t that great? For example, if you have to implement a payment process, you’ll need to gather some data, process the data, make some verifications, perform the transaction, update the transaction status, handle errors or send back a successful response. Let’s use functional programming implement this

def  perform_payment(user_data, payment_data):
    user_verified = verify_user(user_data)
    if not user_verified:
	return “User not valid”

    transaction_data = perform_transaction(user_data, payment_data)
    if not transaction_data[‘was_successful’]:
        update_transaction_log(transaction_data)
        return “Payment cannot be processed”

    update_transaction_log(user_data, payment_data)
    return  “Payment completed successfully”


user_data = get_user_data()
payment_data = get_payment_data()

perform_payment(user_data, payment_data)

This is going to be a lot of fun. There’s nothing wrong with this piece of code from a procedural perspective (maybe from any, I don’t want to argue, we’re just naming things). Let’s think in terms of OOP. “user_data” and “payment_data” can be data objects, the use of data objects can be easily identified. We can have a “User” class and “Payment” class, easy names. But what about the whole transaction? Could I encapsulate all this behavior into a class?. Let’s do that. Ummm, but how can we name that class, so I’m used to using these names: “EntityService”, “EntityProcessor”, “EntityHandler”, (please don’t be shy and ask ChatGPT for more)

class PaymentService():
	
    def set_user(self, user_data):
        self.user = User(**user_data)

    def set_payment(self, payment_data):
	self.payment = Payment(**payment_data)

    def validate_user(self): …
	# Implement user validation

    def perform_transaction(self): …
	# implement transaction logic

Now we’re OOP. This is not an OOP lecture, but I think it’s worth mentioning that this class can be used to implement different kinds of payments or even transactions.

I know I said that we can decide whether or not to use OOP, by finding a name, here I go: If it is so hard to encapsulate a behavior with a proper name that describes a separate and strongly cohesive entity, maybe OOP is not the best. And at the same time we can wisely decide the scope of the class. In this case the PaymentService or PaymentProcessor can be understood as a very cohesive process, and is easy to read. But if you prefer to be more procedural you can create a new module to handle the process (please keep your files as short and focused as you can).

Conclusions

It’s not my intention to replace all that has been said about good naming practices, but to share my experience and advice that can help you to improve the readability of your code by picking good names for your entities. As always, it is important to get involved in the business, understand the context, and focus on the specific problem. Maybe five to ten minutes spent on choosing a name can be really helpful to understand what you are doing, and also could help your teammates to understand your idea and save tons of time during the maintenance.

The NonFunctional Dev