The art and difficulty of naming in programming

Important note: Do not read any of the comments in the thread without solving the challenge.

This article is a follow of my very first article
Every programmer should know these conventions and practices.

So in this article, I'll develop a little more in-depth the point: Give meaningful names.

Giving a meaningful name to our variables, functions, arguments, classes, attributes, and packages is both difficult and an art. Sometimes, and even often, every developer who cares about code quality stumbles upon naming issues. Personally, I can spend a lot of time just thinking about what will the best name for this, and I can choose one, change it later, multiple times until I find one or a colleague helps me to find the one that satisfied me the most, the one that makes me say or think, yeah, that is the perfect name.
Because, the name could drastically change how easily other developers and you (later, in a few years maybe ^_^) will quickly understand your code without necessary reading the details.

In this article, I'll just try to show you the impact of bad names and give more insights and concrete examples in a part2.

I want you to quickly determine without testing what the function does, and after that, find better names to replace the badly named variables in that function in order to make the function more readable and understandable. It's the function in the picture below, it's written in python.
You can start now, and read the rest of the article after you’re done. Are you ready to take the challenge?

So let's go:

The 20 seconds starts right now !!!

Congrats. No matter how much time you took to find it, 10seconds, or 1min, you agree with me that, after you've changed the variable's names with good ones, the function is more obvious to comprehend.
But you know, in reality, even the poorest developer can't write a code that is that much awful, at least, I hope so. In a part 2 of this article, I'll show some real example cases of code naming improvement and best practices.

We are at the end of this short article. Feel free to add in the comments some real cases of naming issues you faced and which name you finally chose.

---

I share what I know because:

The more I learn, the more I realize how much I don't know. (Einstein)

Comments

[Horace FAYOMI]

I drop the solution here anyways.

def print_items_counts(array):
    item_map_count = {}
    for item in array:
        if item_map_count.get(item):
            item_map_count[item] += 1
        else:
            item_map_count[item] = 1

    for item, count in item_map_count.items():
        print(f"{item}: {count}")

[geraldew]

If we're talking about clarity then it is misleading to use

 if item_map_count.get(item):

when there is no apparent use for that value. Instead it is clearer to use

 if item in item_map_count :

So it's not just choice of variable names that affect clarity.

[Horace FAYOMI]

You're right geraldew, thanks.

[yannickkiki]

Nice article, waiting for the part 2!

Just for the record, we could also write this part

if item_map_count.get(item):
    item_map_count[item] += 1
else:
    item_map_count[item] = 1

as this

item_map_count[item] = 1 + item_map_count.get(item, 0)

[Horace FAYOMI]

Beautiful indeed, I like shorthands. Thanks.

[Horace FAYOMI]

And the same thing could be achieved using build in python library collections.Counter like this:

collections.Counter(array)

[Jonas Petri]

That was a great article!
It took me a while to figure out what the program actually did, just because of how poorly the variables were named.

[Horace FAYOMI]

Thanks Jonas.

[Sam oo Líng]

Great! I'm waiting for part 2

[Horace FAYOMI]

Thanks Sammy. Don't, it will come ^_^.

[Tomas Forsman]

This was not really an example of simply bad naming, this was intentionally misleading naming with "booleans".

Here is how I would set bad names:

def process_list(lst):
    result_dict = {}
    for item in lst:
        if result_dict.get(item):
            result_dict[item] += 1
        else:
            result_dict[item] = 1

    for key, value in result_dict.items():
        print(f"{key}: {value}")

And here is how far I could take this with help from the other comments. Perhaps a bit overkill...

from collections import Counter
from typing import List, Any

def print_item_counts(array: List[Any]) -> None:
    """
    Print the count of each item in the input array.

    Args:
        array (List[Any]): The list of items to be counted.

    Example:
        >>> print_item_counts(['apple', 'banana', 'apple'])
        apple: 2
        banana: 1
    """
    if not array:
        print("The array is empty.")
        return

    item_count = Counter(array)
    for item, count in item_count.items():
        print(f"{item}: {count}")

I know Docstring isn't part of this but for the sake of a clarity example I included it; not for readability (it actually makes the code a bit less readable imho) but for documentation and IDE tooling.

Reminder to post the next part 😀