Whenever you are writing code, there is one thing that must always be remembered when writing – it has to be readable. Just like when you had to hand write essays in school, the content of your essay meant nothing if your teacher couldn’t read it. Everyone who codes has their own unique styles and quirks that allow them to get things done. But, if you are going to open source share your work for anyone to see, it should be consistent in its appearance and readability. In this post, I will be sharing five tips to create organized and legible code when working in Python. Let’s get started!
1.) Line Length
I want to start with this tip because it’s quick and to the point – limit each line of code to 79 or fewer characters. That’s it.
2.) Variable Names
In general, you want to try and avoid having your variable names being just one letter or number. However, there are three letters that you absolutely need to avoid if, for whatever reason, you decide you are going to use a one letter variable. Those letters are ‘O’ (can be confused with the number ‘0’), ‘I’ (can be confused with the letter ‘l’), and ‘l’ (can be confused with the number ‘1’). Were you confused as you were reading that sentence? If you were, that proves my entire point.
Also, make sure you don’t use protected words (words that turn green when spelled out) in Python as your variable names, such as list, dict, or str. Along with possibly causing confusion, it will also raise an error if you try and run your code.
3.) Indentation
This primarily applies to when you are writing functions and/or conditional statements. If your indentation is off, your code won’t work. But along with that, you want to have proper indentation if there is more than one argument required in any given function. For example, a function with good indentation can look something like this:
def fake_function(var_one, var_two,
var_three, var_four):
print(var_two)
result = fake_function('var_one', 'var_two',
'var_three', 'var_four')
You can easily see that the arguments for the function are distinguishable from the action the function will perform. Sloppy indentation could look like this:
def fake_function(var_one, var_two,
var_three, var_four):
print(var_two)
result = fake_function('var_one', 'var_two',
'var_three', 'var_four')
Because the indentation is off, it’s hard to tell what exactly the arguments in the function are and what the function’s action is supposed to be.
4.) Operator Placement
Similar to the indentation aspect, if you have code that uses operators – =, +, -, etc. – you want to make sure your operators are located in a logical place that is easy to read. For example, good operator placement could look like this:
income = (gross_wages
+ taxable_interest
+ (dividends - qualified_dividends)
- ira_deduction
- student_loan_interest)
The operators are clearly placed before each variable and you can easily tell what is going on, especially in line 3.
Bad operator placement would look like this:
income = (gross_wages +
taxable_interest +
(dividends - qualified_dividends) -
ira_deduction -
student_loan_interest)
Although it may be easy to understand what’s happening in lines 1 and 2, once you get to line 3 it becomes much more difficult and ambiguous to understand where this code is going. So, the general rule of thumb is to place your operators before your variables in your code so that it makes each step more coherent.
5.) Whitespace
Building back off of the operators from section, you want to make sure that you have a space in between your variable name and the operator itself. This blank space is what’s known as whitespace. Although the operator placement in the most recent example above is incorrect, there is good whitespace placement between the variables and the operators. This also applies to text operators, such as in, and, or, etc. Below is an example of some good whitespace usage:
i = 1
i = i + 1
i += 1
x = i*2 - 1
y = x*x + i*i
z = (x+x) * (i-i)
I want to point out an important exception to what I stated above in lines 4, 5, and 6 (or variables x, y, and z). Notice, for example, in line 4 that i*2 contains no whitespace. That is because it makes it clear to the reader that this is the first step in the math for that line, and that the subtraction will come second. Whichever math property(ies) have the highest priority (remember P.E.M.D.A.S!), you don’t want to include whitespace with that step.
Thank you for reading this post and I hope it helped improve the readability of your code!