Tips and Tricks for Clean and Pythonic Code | Part 2

Photo by Chris Ried on Unsplash

Welcome to the second part from this series Tips and Tricks for Clean and Pythonic Code, where I’ll take you in a short journey to the world of clean and pythonic code, based on my humble experience with Python and my readings in these topics.

In the first part, I talked about Code Formatting and the Black Code Formatter.

In this part, I’ll talk about: Meaningful Names

In a short blog on his website, Martin Fowler quoted a funny joke that says:

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

— Phil Karlton

Finding a name that is meaningful, searchable, descriptive, understandable for you and others, with suitable length is a hard mission while coding.

You may stuck in this dilemma when you need to name a variable, function, class and many other types in your code.

Robert Cecil Martin (Uncle Bob) was talked about different points to take in your account when you name something in the code, he explained them in his popular book Clean Code, and in his talks. Later, many software developers have adapted and developed these ideas and sometimes criticized them.

Intercepting the case battle between snakes and camels, Codebrahma

Casing Style

Python and many other programming languages are case sensitive, and as a programmer you can’t add whitespaces between the phrases of your names.

As a result, there are many well-known casing styles for naming variables and other things in your code when you need more than one word.

Examples on some popular casing styles:

1. snake_case: In this style, the words are separated using underscore, which looks like a flat snake between words. And all letters are in lowercase, but for constants, it’s preferred to be in UPPER_CASE_STYLE.
2. camelCase: By capitalizing each word without spaces or underscores except the first word. The upper case letters look like the camel’s hump.
3. PascalCase: By capitalizing all words without spaces or any separator, it’s named because it’s widely used in Pascal programming language before.

So, what PEP 8's recommendations regarding to this point?

• All letters should be ASCII letters — that is, uppercase and lowercase
  English letters that don’t have accent marks.
• Modules should have short, all lowercase names.
• Class names should be written in PascalCase.
• Constant variables should be written in uppercase SNAKE_CASE.
• Function, method, and variable names should be written in lowercase
  snake_case.
• The first argument for methods should always be named self in
  lowercase.
• The first argument for class methods should always be named cls in
  lowercase.
• Private attributes in classes should always begin with an underscore ( _ ).
• Public attributes in classes should never begin with an underscore ( _ ).

Remember, you are not supposed to not break some of these rules at all, you can customize your own coding style by choosing your preferences (like using camelCase for naming functions).

The important point in the readability factor isn’t the used style, but the consistency in using this customized style. For more details about the naming conventions in PEP 8, from here.

Name Length

Names in code shouldn’t be too long or too short. Because the long names are tedious to type, whereas the short names aren’t clearly enough.

One or two letter name (e.g. hu), abbreviated name(e.g. mon), single word name (e.g. start) are all considered short names. They aren’t clear enough to indicate the exact meaning, in last example: start, start of what?

There are some exceptions for these guidelines, especially when there is a short scope for the variable, or when the name is a popular term like Pi in math, or i and j for iterating over sequences and so on.

Searchable Names

Also, try to make your names searchable, so you can find them when you search in the code editor. For example: email is a general name, and it’s possible to use the same name for the user email and admin email and other users, so it’s more appropriate for you to customize the name: userEmail, adminEmail, emailAttachment …etc.

Don’t Use Jokes in Your Names

Don’t let your humor sense to mess with the code, so don’t use jokes and funny terms in your code. What do you think if you have read a variable name in someone’s code: piece_of_cake ? What is the meaning for this term when others review the code? when you ask the developer, he says: I named the variable depending on my task at that day, it was so easy so I named the variable like that!!

Don’t Overwrite the reserved names

Python allows you to use some of the built-in names in your variables, like list and set. Using these names in your code will make it messy! It won’t raise an error directly, but it will downgrade your code’s readability, and it will raise some errors in some cases, look at this example:

set = {"A", "B", "C"}
set(range(4))

In this example, you overwrite the original set to this created variable, so you’ve lost it when you want to cast the range function values into set data type.

Recap

Stick with a casing style, don’t switch between styles in the same project. Use meaningful names that indicates your intentions well, don’t let others to start guessing the meaning behind your names.

Choose searchable names and don’t let your humor sense to code, i.e. don’t use jokes and strange names in your code. Finally, don’t use the built-in words in the language.