Why are good names so important?
Every name you write in your code is only for humans. The compiler, interpreter or whatever component runs your code will throw your names away and use internal identifiers. So the purpose of your names is literally just for you and every other developer to understand the code. Furthermore, code is far more often read than written.
Indeed, the ratio of time spent reading versus writing is well over 10 to 1. We are constantly reading old code as part of the effort to write new code.
Robert C. Martin, Clean Code: A Handbook of Agile Software Craftsmanship
Consequently, writing readable code by using meaningful names is much more rewarding than just doing it "quick and dirty". It may take a lot longer than doing it quickly, but in the long term you and your colleagues will benefit from the code quality.
Giving bad names is quick
Even if it doesn't seem like it at first glance, sometimes it can be really difficult to give meaningful names. It is often very challenging, especially to make it understandable for outsiders.
Everybody knows the situation, where you have a topic or a goal, and just start coding right away. You are incredibly productive in a short time and the outcome is great. But most of the code we write in this attitude is anything but clean and readable. Consider this small example where the names don't say anything about what the code does.
def statistics_page_7():inp = get_data("sales")inp = clean_data(inp)inp = inp[::-1]av = sum(inp) / len(inp)sum_ = sum([pow(num - av, 2) for num in inp])res = math.sqrt(sum_ / len(inp))return get_page("Statistics", 7, res).render().get_content()
It is very hard to understand what the code actually does. The writer, with all the thoughts and concepts in mind, will understand the code because he wrote it. But after a while, when not dealing with the code for a long time, those insights are gone and the code isn't easily understandable anymore. Furthermore, when the code needs to be adjusted because the requirements changed or there is a bug in it, there's a problem. Getting familiar with poorly written code can be very frustrating and may take a long time. To fully understand the code, the developer possibly needs to debug and dig into it line by line, which is really time-consuming and exhausting.
How to give meaningful names
So, how can you come up with meaningful names? Here are a few tricks that will help you to improve the names in your code!
1. Don't be afraid to use long names
Even if it seems confusing at the fist moment, long names are mostly better than short ones. Especially when the shorter name would hide some relevant information, the better choice is always better to include it in the name. The code will grow, but most information about purpose of the code is in the names. By the way, explaining what the code does with lots of comments isn't a good idea, as you can see in our post to Comments - What you should keep in mind.
2. Keep your functions doing only one thing
By applying this principle, you keep your functions small and reusable. Every function has only one purpose, and therefore it is easy to give them meaningful names. Additionally, you will have more functions and more opportunities to give names. As a result, your code contains more names and tells what it's doing.
3. Let others review your code
Only if someone else understands your code you should be satisfied with the code and your names. There are lots of other advantages of code reviews, so it's recommended to do it anyway. Nonetheless, after your code passed the review, it's not "finished". Writing code is an iterative process that never ends, so you should keep improving it!
With these tricks and some creativity, we can refactor the previous code.
def get_sales_statistics_page() -> str:sales_data: List[float] = get_data(sales)cleaned_sales_data: List[float] = clean_data(sales)sales_standard_deviation: float = calculate_standard_deviation(cleaned_sales_data)return get_html_page(topic="Statistics", page_id=7, template_data=sales_standard_deviation)def calculate_standard_deviation(numbers: List[float]) -> float:variance = calculate_variance(numbers)return math.sqrt(variance)def calculate_variance(numbers: List[float]) -> float:average = calculate_average(numbers)sum_of_squared_difference_from_average = 0for number in numbers:difference_from_average = number - averagesum_of_squared_difference_from_average += pow(difference_from_average, 2)return sum_of_squared_difference_from_average / len(numbers)def calculate_average(numbers: List[float]) -> float:return sum(numbers) / len(numbers)def get_html_page(topic: str, page_id: int, template_data: dict) -> str:page_object = get_page(topic=topic, page_id=page_id, template_data=template_data)rendered_page = page_object.render()return rendered_page.get_content()
After this revision, the code grew a lot but it looks much more inviting. Other developers looking at this code will more likely be motivated to read, understand and extend it.
I hope this post inspired you to reflect the namings in your code and improve the readability. Do you have any tips and best practices for giving meaningful names in code? You're welcome to share and discuss them in the comments!
