Thread by @mathsppblog

Everyone knows that giving proper names to variables and functions is the true programmer's bane.

Here's a thread 👇🧵 with do's and don'ts for naming things in Python 🐍

We can only hold a small number of simultaneous ideas in our 🧠, so proper naming can really help us!

There exist a bunch of naming conventions out there.

Some of them are more common in Python, and others are rarely seen in Python code.

Let me just show you what they look like, and then I'll walk you through when you could use each.

The PascalCase convention is often used with classes.

Notice that when you use PascalCase, you should uppercase all letters of an acronym 👇

In the image, that's exemplified by the `AIPlayer`, where `AI` stands for “artificial intelligence”.

With the rise of the typing advent in Python, the PascalCase convention has also been widely adopted when naming type variables.

In hindsight, this aligns with the fact that PascalCase is used for classes.

After all, classes define new “types”!

PascalCase is great and all, but the bread and butter convention for Python is snake_case.

snake_case is the convention generally used for variables, functions, methods, ...

Another convention that shows up from time to time is the CAPS_LOCK_WITH_UNDERSCORES.

Naming things like this looks a little bit clunky, right?

Funnily enough, this is widely recognised as the convention for global constant variables!

In Python, and elsewhere!

After figuring out what naming convention to use, you need to figure out how verbose the names should be.

Should you write full sentences?

Abbreviate everything?

Use 1-letter names?

When figuring out how long names should be, consider two things:

👉 number of times you're going to use the name:

If a name is used very often, e.g. a function you call all the time, or a variable you access very often, that name can be shorter.

👉 distance between definition of the name and its usage:

If you define a name and only use it once in a completely different file, maybe that name should be more verbose.

As for the actual names you pick, there are also a couple of guidelines you can follow:

👉 always use the same spelling:

👉 always use the same vocabulary:

👉 use a name that reflects WHAT we are working with, not the type of data:

👉 prefer verbs for functions and nouns for variables:

Now that we've seen many tips, let's look at a case study.

Here's a function that was poorly named.

The function behaves like this:

>>> myfunc("abcdef")
'AbCdEf'
>>> myfunc("ABCDEF")
'AbCdEf'
>>> myfunc("A CDEF")
'A CdEf'

Take a moment to think about how you would improve the names that are used in this function.

Rework the function...

And now, let me show you what I would suggest 👇

👉 the function name `alternate_casing` now indicates what it does to its argument;

👉 the parameter is now called `text` to help us understand what might get passed in as an argument;

👉 the list we are building is now called `letters`, to help us guess what is being appended.

👉 and a personal quirk of mine, I prefer to use `idx` as the name for an index variable to be extra explicit.

(For an added 🏆 challenge, you can try to refactor this function to improve it.

This is the function I used in my Pydon'ts talk 👇)

I should say 2 more important things.

1️⃣ The context you are programming in also plays an important role in the names you pick.

For example, depending on whether you are writing code for a domain-specific package, some abbreviations may or may not make sense.

2️⃣ These are just guidelines, not RULES.

You should always use common sense to judge whether or not these guidelines make sense.

As an example, if you are contributing to a codebase, it's more important to follow that codebase's standards than to follow these guidelines.

That's it for this thread 👍

If you are interested in Python 🐍, and knowledge-packed tweets and threads, follow me @mathsppblog for more 😉

If this thread was useful to you, retweet it!

This thread was based off of an article I wrote a while ago on naming.

The article goes in more detail about some subtleties and includes more examples of what I talked about.

Check it out, and I'll see you around 👋

mathspp.com/blog/pydonts/n…