Python

How to Name Things: The Hardest Problem in Programming

Naming do’s and don’ts by Google

Photo by Jexo on Unsplash

There’s this popular saying:

There are only two hard things in Computer Science: cache invalidation and naming things.

— Phil Karlton

But why is naming things hard?

It’s well put in this hacker news comment.

Naming things is hard because a proper name imparts the essence of the thing you’re naming. To understand the essence of the thing, you have to understand what role it serves, what else it interacts with, and what part of that is interface and what is implementation.

Naming is identifying concepts that matter — and occasionally realizing that the thing you just wrote, but can’t name, is not a thing that should exist. It’s part of understanding what your system really is and what it does.

The naming part, the mapping of words to objects, is easy. What’s hard is breaking down a system into parts with obvious names.

source

Here’s what Google recommends for naming functions, variables, and files (taken from their style guide)

Hopefully, this helps you write cleaner code and waste less time figuring out how to name things.

Before we start, are you utilizing the Python collections module to write efficient Python Code?

Python Collections Module: Essential Tools for Efficient Coding

The fundamentals

1. Names should be descriptive.
2. Avoid abbreviation.

Do not use ambiguous or unfamiliar abbreviations to readers outside your project; do not abbreviate by deleting letters within a word.

Essentially, bad names are too general, too short, or too long.

Names you should avoid ❌

Remember to avoid these 5 things when naming anything

1. single character names, except for specifically allowed cases (see below)
2. dashes (-) in any package/module name
3. __double_leading_and_trailing_underscore__ names (reserved by Python)
4. offensive terms
5. names that needlessly include the type of the variable (for example: id_to_name_dict)

Examples of single characters that are allowed

• counters or iterators (e.g. i, j, k, v)
• e as an exception identifier in try/except statements.
• f as a file handle in with statements
• private TypeVars with no constraints (e.g. _T, _U, _V)

Naming Conventions

Some naming conventions that exist and what Google says about them

• “Internal” == internal to a module or protected or private within a class.
• Prepending a single underscore (_) has support for protecting module variables and functions (linters will flag protected member access).
• Prepending a double underscore (__ aka “dunder”) is discouraged as use as it impacts readability and testability and isn’t really private. Prefer a single underscore.
• Place related classes and top-level functions together in a module. Unlike Java, there is no need to limit yourself to one class per module.
• Use CapWords for class names, but lower_with_under.py for module names.
• There is no One Correct Way to name test methods: Underscores may appear in unittest method names starting with test to separate logical components of the name, even if those components use CapWords. One possible pattern is test<MethodUnderTest>_<state>; for example testPop_EmptyStack is okay.

Now onto files.

File Naming

Python filenames must have a .py extension and must not contain dashes (-). This allows them to be imported and unittested.

Here’s a nice table with examples.

Guido’s recommendations

Math notations

But what if you’re implementing algorithms with math notations and you have to follow the established convention from the literature?

Google says: “reference the source of all naming conventions in a comment or docstring or, if the source is not accessible, clearly document the naming conventions.”

That’s all the advice from Google

Thank you for reading!

If you have suggestions on naming things, feel free to comment below!

Looking for book recommendations? Here’s what some of the top computer scientists read 👇

Books Recommended by Computer Scientists

Follow me on LinkedIn and Twitter for awesome Data Science and Programming resources.

Like my writing? Join Medium for the price of ☕.

You’ll be supporting me directly 🤗

Join Medium with my referral link - Benedict Neo