Have you ever come across a really poorly written piece of Python code? I’m talking about a tangled mess where you had to spend hours just trying to understand what piece of code goes where. I know a lot of you will nod your head at this.
Writing code is one part of a data scientist’s or analyst’s role. Writing beautiful and neat Python code, on the other hand, is a different ball game altogether. This could well make or break your image as a proficient programmer in the analytics or data science space (or even in software development).
Remember – our Python code is written once, but read a billion times over, potentially by viewers who are not accustomed to our style of programming. This takes on even more importance in data science. So how do we write this so-called beautiful Python code?
Welcome to the Python Style Guide!
A lot of folks in the data science and analytics domains come from a non-programming background. We start off by learning the basics of programming, move on to comprehend the theory behind machine learning, and then get cracking on the dataset. In this process, we often do not practice hardcore programming or pay attention to programming conventions.
That’s the gap this Python Style Guide will aim to address. We will go over the programming conventions for Python described by the PEP-8 document and you’ll emerge as a better programmer on the other side!
Are you completely new to Python programming? Then I’d suggest first taking the free Python course before understanding this style guide.
There are a couple of reasons that make formatting such an important aspect of programming, especially for data science projects:
Good code formatting will inevitably improve the readability of your code. This will not only present your code as more organized but will also make it easier for the reader to easily understand what is going on in the program. This will especially be helpful if your program runs into thousands of lines. With so many dataframe, lists, functions, plots, etc. you can easily lose track of even your own code if you don’t follow the correct formatting guidelines!
If you are collaborating on a team project, which most data scientists will be, good formatting becomes an essential task. This makes sure that the code is understood correctly without any hassle. Also, following a common formatting pattern maintains consistency in the program throughout the project lifecycle.
Having a well-formatted code will also help you when you need to fix bugs in your program. Wrong indentation, improper naming, etc. can easily make debugging a nightmare! Therefore, it is always better to start off your program on the right note!
With that in mind, let’s have a quick overview of the PEP-8 style guide we will cover in this article!
PEP-8, or Python Enhancement Proposal, is the style guide for Python programming. It was written by Guido van Rossum, Barry Warsaw, and Nick Coghlan. It describes the rules for writing a beautiful and readable Python code.
Following the PEP-8 style of coding will make sure there is consistency in your Python code, making it easier for other readers, contributors, or yourself, to comprehend it.
This article covers the most important aspects of the PEP-8 guidelines, like how to name Python objects, how to structure your code, when to include comments and whitespaces, and finally, some general programming recommendations that are important but easily overlooked by most Python programmers.
Let’s learn to write better code!
The official PEP-8 documentation can be found here.
Shakespeare famously said – “What’s in a name?”. If he had encountered a programmer back then, he would have had a swift reply – “A lot!”.
Yes, when you write a piece of code, the name you choose for the variables, functions, and so on, has a great impact on the comprehensibility of the code. Just have a look at the following piece of code:
# Function 1 def func(x): a = x.split()[0] b = x.split()[1] return a, b print(func('Analytics Vidhya')) # Function 2 def name_split(full_name): first_name = full_name.split()[0] last_name = full_name.split()[1] return first_name, last_name print(name_split('Analytics Vidhya'))
# Outputs ('Analytics', 'Vidhya') ('Analytics', 'Vidhya')
Both the functions do the same job, but the latter one gives a better intuition as to what it is happening under the hood, even without any comments! That is why choosing the right names and following the right naming convention can make a huge difference while writing your program. That being said, let’s look at how you should name your objects in Python!
Try the above code in the live coding window below.
These tips can be applied to name any entity and should be followed religiously.
thisVariable, ThatVariable, some_other_variable, BIG_NO
this_could_be_a_bad_name = “Avoid this!” t = “This isn\’t good either”
X = “My Name” # Avoid this full_name = “My Name” # This is much better
1_name = “This is bad!”
phone_ # Bad name
blog = "Analytics Vidhya"
awesome_blog = "Analytics Vidhya"
O = 0 + l + I + 1
# Avoid def con(): ... # This is better. def connect(): ...
# Avoiding name clashes. def break_time(break_): print(“Your break time is”, break_,”long”)
# Follow CapWord convention class MySampleClass: pass
This will make sure the attribute __age in class Person is accessed as _Person__age. This is Python’s name mangling and it makes sure there is no name collision
class Person: def __init__(self): self.__age = 18 obj = Person() obj.__age # Error obj._Person__age # Correct
class CustomError(Exception): “””Custom exception class“””
class SampleClass: def instance_method(self, del_): print(“Instance method”) @classmethod def class_method(cls): print(“Class method”)
testpackage # package name sample_module.py # module name
# Following constant variables in global.py module PI = 3.14 GRAVITY = 9.8 SPEED_OF_Light = 3*10**8
Now that you know how to name entities in Python, the next question that should pop up in your mind is how to structure your code in Python! Honestly, this is very important, because without proper structure, your code could go haywire and can be the biggest turn off for any reviewer.
So, without further ado, let’s get to the basics of code layout in Python!
It is the single most important aspect of code layout and plays a vital role in Python. Indentation tells which lines of code are to be included in the block for execution. Missing an indentation could turn out to be a critical mistake.
Indentations determine which code block a code statement belongs to. Imagine trying to write up a nested for-loop code. Writing a single line of code outside its respective loop may not give you a syntax error, but you will definitely end up with a logical error that can be potentially time-consuming in terms of debugging.
Follow the below mentioned key points on indentation for a consistent structure for your Python scripts.
# Example if value<0: print(“negative value”) # Another example for i in range(5): print(“Follow this rule religiously!”)
It is recommended to use Spaces over Tabs. But Tabs can be used when the code is already indented with tabs.
if True: print('4 spaces of indentation used!')
There are several ways of handling such a situation. One way is to align the succeeding statements with the opening delimiter.
# Aligning with opening delimiter. def name_split(first_name, middle_name, last_name) # Another example. ans = solution(value_one, value_two, value_three, value_four)
A second way is to make use of the 4-space indentation rule. This will require an extra level of indentation to distinguish the arguments from the rest of the code inside the block.
# Making use of extra indentation. def name_split( first_name, middle_name, last_name): print(first_name, middle_name, last_name)
Finally, you can even make use of “hanging indents”. Hanging indentation, in the context of Python, refers to the text style where the line containing a parenthesis ends with an opening parenthesis. The subsequent lines are indented until the closing parenthesis.
# Hanging indentation. ans = solution( value_one, value_two, value_three, value_four)
if-statements with multiple conditions naturally contain 4 spaces – if, space, and the opening parenthesis. As you can see, this can be an issue. Subsequent lines will also be indented and there is no way of differentiating the if-statement from the block of code it executes. Now, what do we do?
Well, we have a couple of ways to get our way around it:
# This is a problem. if (condition_one and condition_two): print(“Implement this”)
One way is to use an extra level of indentation of course!
# Use extra indentation. if (condition_one and condition_two): print(“Implement this”)
Another way is to add a comment between the if-statement conditions and the code block to distinguish between the two:
# Add a comment. if (condition_one and condition_two): # this condition is valid print(“Implement this”)
Let’s say you have a long dictionary of values. You put all the key-value pairs in separate lines but where do you put the closing bracket? Does it come in the last line? The line following it? And if so, do you just put it at the beginning or after indentation?
There are a couple of ways around this problem as well.
One way is to align the closing bracket with the first non-whitespace character of the previous line.
# learning_path = { ‘Step 1’ : ’Learn programming’, ‘Step 2’ : ‘Learn machine learning’, ‘Step 3’ : ‘Crack on the hackathons’ }
The second way is to just put it as the first character of the new line.
learning_path = { ‘Step 1’ : ’Learn programming’, ‘Step 2’ : ‘Learn machine learning’, ‘Step 3’ : ‘Crack on the hackathons’ }
If you are trying to fit too many operators and operands into a single line, it is bound to get cumbersome. Instead, break it into several lines for better readability.
Now the obvious question – break before or after operators? The convention is to break before operators. This helps to easily make out the operator and the operand it is acting upon.
# Break lines before operator. gdp = (consumption + government_spending + investment + net_exports )
Bunching up lines of code will only make it harder for the reader to comprehend your code. One nice way to make your code look neater and pleasing to the eyes is to introduce a relevant amount of blank lines in your code.
# Separating classes and top level functions. class SampleClass(): pass def sample_function(): print("Top level function")
# Separating methods within class. class MyClass(): def method_one(self): print("First method") def method_two(self): print("Second method")
def remove_stopwords(text): stop_words = stopwords.words("english") tokens = word_tokenize(text) clean_text = [word for word in tokens if word not in stop_words] return clean_text
def remove_stopwords(text): stop_words = stopwords.words("english") tokens = word_tokenize(text) clean_text = [word for word in tokens if word not in stop_words] clean_text = ' '.join(clean_text) clean_text = clean_text.lower() return clean_text
When you are writing code in Python, you cannot squeeze more than 79 characters into a single line. That’s the limit and should be the guiding rule to keep the statement short.
# Breaking into multiple lines. num_list = [y for y in range(100) if y % 2 == 0 if y % 5 == 0] print(num_list)
Part of the reason why a lot of data scientists love to work with Python is because of the plethora of libraries that make working with data a lot easier. Therefore, it is given that you will end up importing a bunch of libraries and modules to accomplish any task in data science.
import numpy as np import pandas as pd df = pd.read_csv(r'/sample.csv')
import numpy as np import pandas as pd import matplotlib from glob import glob import spaCy import mypackage
from math import ceil, floor
Understanding an uncommented piece of code can be a strenuous activity. Even for the original writer of the code, it can be difficult to remember what exactly is happening in a code line after a period of time.
Therefore, it is best to comment on your code then and there so that the reader can have a proper understanding of what you tried to achieve with that particular piece of code.
# Remove non-alphanumeric characters from user input string. import re raw_text = input(‘Enter string:‘) text = re.sub(r'\W+', ' ', raw_text)
info_dict = {} # Dictionary to store the extracted information
def square_num(x): """Returns the square of a number.""" return x**2 def power(x, y): """Multiline comments. Returns x raised to y. """ return x**y
Whitespaces are often ignored as a trivial aspect when writing beautiful code. But using whitespaces correctly can increase the readability of the code by leaps and bounds. They help prevent the code statement and expressions from getting too crowded. This inevitably helps the readers to go over the code with ease.
# Correct way df[‘clean_text’] = df[‘text’].apply(preprocess)
# Correct name_split = lambda x: x.split() # Correct
# Correct print(‘This is the right way’) # Correct for i in range(5): name_dict[i] = input_list[i]
# Correct ans = x**2 + b*x + c
They should be treated as the lowest priority operators. Equal spaces must be included around each colon
# Correct df_valid = df_train[lower_bound+5 : upper_bound-5]
def exp(base, power=2): return base**power
# Correct brooklyn = [‘Amy’, ‘Terry’, ‘Gina’, 'Jake'] count = 0 for name in brooklyn: if name == ‘Jake’: print(‘Cool’) count += 1
Often, there are a number of ways to write a piece of code. And while they achieve the same task, it is better to use the recommended way of writing cleaner code and maintain consistency. I’ve covered some of these in this section.
# Wrong if name != None: print("Not null") # Correct if name is not None: print("Not null")
# Correct if valid: print("Correct") # Wrong if valid == True: print("Wrong")
# Prefer this def func(x): return None # Over this func = lambda x: x**2
try: x = 1/0 except ZeroDivisionError: print('Cannot divide by zero')
# Wrong def sample(x): if x > 0: return x+1 elif x == 0: return else: return x-1 # Correct def sample(x): if x > 0: return x+1 elif x == 0: return None else: return x-1
# Correct if name.endswith('and'): print('Great!')
Formatting won’t be a problem when you are working with small programs. But just imagine having to follow the correct formatting rules for a complex program running into thousands of lines! This will definitely be a difficult task to achieve. Also, most of the time, you won’t even remember all of the formatting rules. So, how do we fix this problem? Well, we could use some autoformatters to do the job for us!
Autoformatter is a program that identifies formatting errors and fixes them in place. Black is one such autoformatter that takes the burden off your shoulders by automatically formatting your Python code to one that conforms to the PEP8 style of coding.
You can easily install it using pip by typing the following command in the terminal:
pip install black
But let’s see how helpful black actually is in the real world scenario. Let’s use it to formats the following poorly typed program:
Now, all we have to do is, head over to the terminal and type the following command:
black style_script.py
Once you have done that, if there are any formatting changes to be made, black would have already done that in place and you will get the following message:
These changes will be reflected in your program once you try to open it again:
As you can see, it has correctly formatted the code and will definitely be helpful in case you miss out on any of the formatting rules.
Black can also be integrated with editors like Atom, Sublime Text, Visual Studio Code, and even Jupyter notebooks! This will surely be one extension you can never miss to add-on to your editors.
Besides black, there are other autoformatters like autopep8 and yapf which you can try out as well!
We have covered quite a lot of key points under the Python Style Guide. If you follow these consistently throughout your code, you are bound to end up with a cleaner and readable code.
Also, following a common standard is beneficial when you are working as a team on a project. It makes it easier for other collaborators to understand. Go ahead and start incorporating these style tips in your Python code!
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
Very Good !
Hi! Thanks for the article.I have found two minor typos:In the Brooklyn example, you seem to have missed the single quotation marks for 'Jake'.When referring to your article about lambda functions, you only used "amda function" for the hyperlink.
Thanks for pointing out the suggested formatting erros!
I am completely new in python programming. Can you please suggest from where I can learn python basics
Hi You can check out our free course on Python for Data Science - https://courses.analyticsvidhya.com/courses/introduction-to-data-science. It goes through the basics of Python programming language in the beginning which should solve your purpose. I hope this helps.
Just pointing out something minor here. Underscores, which are special characters are recommended to be used in cases where the variable is a restricted python name. Eg:filter_ = “foo” would be perfectly fine to use and is recommended in the PEP8 style guide
Yes, I have mentioned this in my article.
Thank you for writing this article, it was really informative and helped me prepare for my upcoming assignment. Your article was to the point and helped me clear some doubts, thanks again.