My 3 Worst Python Function Names

3 unclear function names and how to improve them.

Written by Reka Horvath on

Function definition
Unclear function names make code harder to understand

function definition with the comment What is the function doing?

Last week, we published a blog post about the Voldemort rule, that helps you avoid some unwanted names in your code. This time, we’re giving some more inspiration with 3 function names that really should be avoided.

add_tt

As the comment shows, this function name turned out to be quite a mystery even to its author (me). It’s from a small tool that I use to enter the thinking times used per move during a chess game.

The “big question” in the comment can be split into multiple smaller questions.

Where’s The Problem?

The abbreviation tt has multiple drawbacks. It’s not obvious what it stands for. It isn’t specific enough: It’s unclear which component / format of the thinking time we’re referring to.

This makes it a great candidate for a Voldemort rule.

Caveat: When defining which name to avoid, use _tt, including the _ prefix. A Voldemort rule only for tt would also flag valid names like “pattern”.

Better Name

A better name should:

One candidate: add_remaining_minutes_to_move

process

This is probably the winner in the category “missing information”. The name fails to communicate at least 2 crucial things:

Where’s The Problem?

This is a typical example of how a (somewhat) successful software “outgrew” its initial design.

When I was writing that code, it seemed to be quite clear what process means. This was the very first iteration of this tool and everything looked straightforward. We had 2 input files and 1 output file. It also seemed to be logical that we process the input file “line by line” or “move by move”.

Don’t get me wrong: process was an unclear name even at that point. But in the context of a small, single-purpose tool, it wasn’t such a big effort to figure out what gets processed and how.

Then the tool turned out to be quite handy, so I decided to add some further features: calculate stats, draw charts. In its current version, the output consists of 5 different files per game. That’s of course great news. (Assuming that I’m learning something from all that information… But that’s the topic of another blog post.😃)

The increasing number of features made the tool more complex. Suddenly, we had a workflow of 3 steps feeding into each other. In the context of such a complex tool, a name like process got much more problematic. Now, it was unclear:

Keep in mind that we’re still talking about a tiny tool, not about an enterprise project management software.

Compared to how quickly the feature set and the team of a successful software product grows, this is still tiny.

But even in that scale, it was funny to observe how more features and more complexity make naming more important.

Better Name

A better name should:

One candidate: add_time_data_to_pgn_line

extract_entries

Although it’s a longer name consisting of 2 words, it has similar problems as the process function.

As in the case of process: The more complex the application becomes, the more difficult it gets to figure this out from the code.

If this seems to be too much information to cram into a single name, you can also provide more details in the docstring. For example:

Where’s The Problem?

“entry” is an example for the anti-pattern “overly general name” mentioned in last week’s post. It doesn’t communicate neither the content, nor the format.

These names are fine occasionally or as a placeholder during development. But if you find yourself overusing it (as I’m clearly doing in this code 😏), consider introducing a Voldemort rule for it.

Better Name

A better name should:

One candidate: create_move_stat_records

Conclusion

Naming is a topic which is worth revisiting again and again. A name which used to be great (or at least OK) might have become ambiguous or even misleading as the business and technology context has changed.

A good technique is to ask some questions. If a name keeps as many questions unanswered as the examples in this post, it’s probably time to change it.

Do you have some similar examples? Or quite the contrary, some awesome names?

Reach out at hello@sourcery.ai or on Twitter @SourceryAI. Join the Sourcery Discord Community.