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.

• What does tt mean? (It's a quite obscure abbreviation, even if the whole tool's topic is "thinking times".)
• Once you've figured out that tt is an abbreviation of "thinking_time", the next question is: In which format do we add it?
• And where do we add it?

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:

• Replace tt with something more specific like remaining_minutes or minutes_left.
• Note where we add sth, like to_move or evtl per_move

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:

• scope: What do we process?
• result: How is a "processed" something different from an "unprocessed" one?

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:

• Where are we in the workflow?
• What are the inputs for this step?
• Which output file are we creating?

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

• There's a single use case / situation.
• There's a single (type of) user.
• The number of output files is 5, not 500.
• There's 1 developer.
• This developer has a decent domain knowledge.

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:

• Communicate that the scope is a line in a pgn file.
• Replace the overly general word process with something more specific.

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.

• Where do we extract these entries from?
• What are these entries? What data do they contain?

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:

• a link to an example input file
• an example "entry" with all its properties

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:

• Replace the overly general word entry with something more specific.
• Say where do we extract from or omit the word extract.

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.

Related Blog Posts

• Consistent Naming with Voldemort Rules