Lesson 14 - Common Python beginner mistakes - Can you name variables?

In today's Python tutorial, we'll show you most common good practices for programming in Python. Not just beginners often break them and make unnecessary mistakes in their programs. Maybe you make them too?

Senior Programmer's Word

Congratulations on mastering the first lessons of Basic Python Constructs!

I prepared the material for today's lesson, based on 20 years of programming experience. As an editor-in-chief and also a lecturer, hundreds, maybe thousands of source codes created by the community have passed through my hands. It was not difficult to notice that most of them, although working fine, contain unnecessary errors, which are also repeated over and over again. Surprisingly, mistakes were often made not only by beginner, but also by more experienced programmers - I used to do them too.

I have come to conclusion, that one basic and wrong assumption is:

✗ The program is correct, when it works.

Programs vs. Houses

If we build a house, the fact that we like it and that wind doesn't blow inside of it, is not an ultimate sign of everything being great. The house must have a well-thought-out architecture, and if it has no foundations, it will start to collapse sooner or later.

Programming is often compared to construction in terms of architecture - in our case, the software one. Let's explain why.

The human brain can only work with a limited amount of information at a time. Simply put, if a program is messy, from a certain point on, the programmer would have to keep more things in mind than is humanly possible. Adding additional functions to such a program will always cause an error in the application. In practice, this usually results in the author's loss of "having fun" with their hobby project, or the commercial project goes bankrupt, because it's "already got too complicated".

Let's take another example - when our household is arranged in such a way that a hammer is stored in a first-aid kit, which hangs somewhere in the basement, it'll probably be difficult for us to do anything effectively in it. Although this example sounds absurd, its program equivalents are being done daily.

When Is the Program Correct?

That's easy. The program is correct if it:

• works
• follows good practices and
• is tested.

Note that functionality from the program user's point of view represents only 1/3 of the program's quality criteria. Just like raw functionality of the house from it's resident's point of view represents only a fraction of its real construction quality.

We'll talk about breaking good practices and managing quality of code today. We care about you being excellent, so you'll find a few more of these lessons across our courses.

How to Name Variables Correctly?

It is said that we use 10% of time for programming something and 90% for coming up with a name for it This is, of course, an exaggeration, but the joke comes across the need to spend some time figuring out the names of our variables. It's important that everyone, including us when returning to our own code after a few months, understands what the variable is used for. In general, you can rely on a simple rule:

We always name variables according to what they contain, and not according to what they are used for in the program.

Let's compare the following 2 codes:

display = "Capital Cities"
text2 = "John Smith"
list = []
foo = 0
calculation = 0

topic = "Capital Cities"
name = "John Smith"
answers = []
bonus = 0
total_bonus = 0

Both codes create variables for a simple console quiz. In the first example, it's unclear, what some of the variables contain. E.g. naming a variable list has about the same informational value, as if we named it variable.

A common mistake is that we want to save a result of a calculation, thus naming the variable calculation. However, the calculation is not related to the variable at all, it is an action - the variable always contains a value (result of the action), total_bonus in case of the quiz code. Similarly, in the first code, a variable is named display because we display it somewhere. In the second code, we can clearly see that it contains the topic of the quiz.

Sincerely - which of you would understand that the code on the left is a quiz program?

We also never name the variables auxiliary or aux, etc.

Pay Attention to "Spanglish" and Diacritics

On our level, in beginner's code, it doesn't matter what language we use to name our variables. As long as we don't send our monolingual, English speaking colleague a code in Spanish, of course.

Across a project, we name our variables using one language only and without diacritics!

Let's see some examples again:

notificación = "Hola!"
count = 0

notification = "Hello!"
count = 0

We never use accent characters (such as ó) etc. in identifiers (e.g. variable names). This does not apply to values stored in them, of course.

Although modern programming languages support UTF-8 encoding in identifiers, it is very easy to forget an accent - we suddenly use a completely different variable in that case! In addition, the source code file can be processed by an application that does not support the encoding - this typically happens over time (for example, it is sometimes a problem to display accents in email attachment, because of the mail client).

Multiword Variables

Today's applications are increasingly complex. It often happens that one word is not enough to describe what is stored in a variable. Then it is better to use more words. In current business applications, short identifiers from the 80's are being replaced with relatively long names such as user_object_output_stream_factory and the like.

However, such a long name only makes sense in a complex application, where there are several similar variables, so we have to add another word. We'll not create a variable named text_with_a_hello_world_greeting in a Hello World application. All we need for the variable's name is greeting, given there's no other greeting

Separating Words

For readability, in such a variable name, we must somehow separate the words:

• We separate words according to the convention of the given programming language. In Python, this is specified in the PEP 8 document, which recommends using underscores to separate words. This notation is sometimes also called snake_case (the words are lowercase and separated by underscores - the text then, with a little imagination, looks like it's "crawling"). In other languages, a capital letter such as camelCase and other notations can be used to separate words. We use other notations in Python rarely, only when we have a good reason to do so - for example, if we work with a library ported from another system, that uses a different notation, which we want to preserve.
• If possible, we avoid numbering variables and do not write numbers in words at all - no greeting2 or greeting_two. "Two" says nothing about what the greeting contains.

Let's look at some examples:

message1 = "Hello"
messageTwo = "Uh, hi"

received = input_buffer[0] # text, bytes, message, order, ...?
sent = "Uh, hi"

receivedmessage = "Hello"
sentmessage = "Uh, hi"

received_message = "Hello"
sent_message = "Oh hello!"

We Don't Use Abbreviations

Let's start this chapter with a quote:

Everyone was wondering what's the DATOBI column for. Then one day someone found out it's the date of birth, apparently.

This bad practice is actually the opposite of multiword variable names. We do not invent nonsensical abbreviations, for example, no one knows rm is meant to be received_message. The mnemonic can be:

If someone other than us looks at the code, they should know exactly what's stored in the variable.

rm = "Yes"
mc = 5

message = "Yes"
message_count = 5

As we promised, we'll return to the topic of good practices several more times in similar, rather relaxing lessons

In the next lesson, Common Python Beginner Mistakes - Do You Make Them Too?, we'll go through the most common beginner mistakes in Python, in terms of collections naming, bool expressions, and DRY.