Overview The Python Style Guide will enable you to write neat and beautiful Python code Learn the different Python conventions and other nuances of Python programming in this Style Guide Introduction 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.
Python Style Guide Contents What is PEP8? Understanding Python Naming Conventions Python Style Guide’s Code Layout Getting Familiar with using Comments Whitespaces in your Python Code General Programming Recommendations for Python What is PEP-8? 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 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.
Understanding Python Naming Convention 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! General Tips to Begin With These tips can be applied to name any entity and should be followed religiously.
Try to follow the same pattern – consistency is the key! thisVariable, ThatVariable, some_other_variable, BIG_NO Avoid using long names while not being too frugal with the name either this_could_be_a_bad_name = “Avoid this!” t = “This isn’t good either” Use sensible and descriptive names.
This will help later on when you try to remember the purpose of the code X = “My Name” # Avoid this full_name = “My Name” # This is much better Avoid using names that begin with numbers 1_name = “This is bad!” Avoid using special characters like @, !, #, $, etc.
in names phone_ # Bad name Naming Variables Variable names should always be in lowercase blog = “Analytics Vidhya” For longer variable names, include underscores to separate_words.
This improves readability awesome_blog = “Analytics Vidhya” Try not to use single-character variable names like ‘I’ (uppercase i letter), ‘O’ (uppercase o letter), ‘l’ (lowercase L letter).
They can be indistinguishable from numerical 1 and 0.
Have a look: O = 0 + l + I + 1 Follow the same naming convention for Global variables Naming Functions Follow the lowercase with underscores naming convention Use expressive names # Avoid def con(): .
# This is better.
def connect(): .
If a function argument name clashes with a keyword, use a trailing underscore instead of using an abbreviation.
For example, turning break into break_ instead of brk # Avoiding name clashes.
def break_time(break_): print(“Your break time is”, break_,”long”) Class names Follow CapWord (or camelCase or StudlyCaps) naming convention.
Just start each word with a capital letter and do not include underscores between words # Follow CapWord convention class MySampleClass: pass If a class contains a subclass with the same attribute name, consider adding double underscores to the class attribute 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 Use the suffix “Error” for exception classes class CustomError(Exception): “””Custom exception class“”” Naming Class Methods The first argument of an instance method (the basic class method with no strings attached) should always be self.
This points to the calling object The first argument of a class method should always be cls.
This points to the class, not the object instance class SampleClass: def instance_method(self, del_): print(“Instance method”) @classmethod def class_method(cls): print(“Class method”) Package and Module names Try to keep the name short and simple The lowercase naming convention should be followed Prefer underscores for long module names Avoid underscores for package names testpackage # package name sample_module.
py # module name Constant names Constants are usually declared and assigned values within a module The naming convention for constants is an aberration.
Constant names should be all CAPITAL letters Use underscores for longer names # Following constant variables in global.
py module PI = 3.
14 GRAVITY = 9.
8 SPEED_OF_Light = 3*10**8 Python Style Guide’s Code Layout 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! Indentation 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.
Always follow the 4-space indentation rule # Example if value<0: print(“negative value”) # Another example for i in range(5): print(“Follow this rule religiously!”) Prefer to use spaces over tabs 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!) Break large expressions into several lines 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) Indenting if-statements can be an issue 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”) Brackets need to be closed 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’ } Break line before binary operators 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 ) Using Blank Lines 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.
Top-level functions and classes should be separated by two blank lines # Separating classes and top level functions.
class SampleClass(): pass def sample_function(): print(“Top level function”) Methods inside a class should be separated by a single blank line # Separating methods within class.
class MyClass(): def method_one(self): print(“First method”) def method_two(self): print(“Second method”) Try not to include blank lines between pieces of code that have related logic and function 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 Blank lines can be used sparingly within functions to separate logical sections.
This makes it easier to comprehend the code 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 Maximum line length No more than 79 characters in a line 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.
You can break the statement into multiple lines and turn them into shorter lines of code # Breaking into multiple lines.
num_list = [y for y in range(100) if y % 2 == 0 if y % 5 == 0] print(num_list) Imports 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.
Should always come at the top of the Python script Separate libraries should be imported on separate lines import numpy as np import pandas as pd df = pd.
read_csv(r/sample.
csv) Imports should be grouped in the following order: Standard library imports Related third party imports Local application/library specific imports Include a blank line after each group of imports import numpy as np import pandas as pd import matplotlib from glob import glob import spaCy import mypackage Can import multiple classes from the same module in a single line from math import ceil, floor Getting Familiar with Proper Python Comments 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.
General Tips for Including Comments Always begin the comment with a capital letter Comments should be complete sentences Update the comment as and when you update your code Avoid comments that state the obvious Block Comments Describe the piece of code that follows them Have the same indentation as the piece of code Start with a # and a single space # Remove non-alphanumeric characters from user input string.
import re raw_text = input(‘Enter string:‘) text = re.
sub(rW+, , raw_text) Inline comments These are comments on the same line as the code statement Should be separated by at least two spaces from the code statement Starts with the usual # followed by a whitespace Do not use them to state the obvious Try to use them sparingly as they can be distracting info_dict = {} # Dictionary to store the extracted information Documentation String Used to describe public modules, classes, functions, and methods Also known as “docstrings” What makes them stand out from the rest of the comments is that they are enclosed within triple quotes ””” If docstring ends in a single line, include the closing “”” on the same line If docstring runs into multiple lines, put the closing “”” on a new line 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 in your Python Code 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.
Key points Avoid putting whitespaces immediately within brackets # Correct way df[‘clean_text’] = df[‘text’].
apply(preprocess) Never put whitespace before a comma, semicolon, or colon # Correct name_split = lambda x: x.
split() # Correct Don’t include whitespaces between a character and an opening bracket # Correct print(‘This is the right way’) # Correct for i in range(5): name_dict[i] = input_list[i] When using multiple operators, include whitespaces only around the lowest priority operator # Correct ans = x**2 + b*x + c In slices, colons act as binary operators 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] Trailing whitespaces should be avoided Don’t surround = sign with whitespaces when indicating function parameters def exp(base, power=2): return base**power Always surround the following binary operators with single whitespace on either side: Assignment operators (=, +=, -=, etc.
) Comparisons (==, <, >, !=, <>, <=, >=, in, not in, is, is not) Booleans (and, or, not) # Correct brooklyn = [‘Amy’, ‘Terry’, ‘Gina’, Jake] count = 0 for name in brooklyn: if name == ‘Jake’: print(‘Cool’) count += 1 General Programming Recommendations for Python 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.
For comparison to singletons like None, always use is or is not.
Do not use equality operators # Wrong if name != None: print(“Not null”) # Correct if name is not None: print(“Not null”) Don’t compare boolean values to TRUE or FALSE using the comparison operator.
While it might be intuitive to use the comparison operator, it is unnecessary to use it.
Simply write the boolean expression # Correct if valid: print(“Correct”) # Wrong if valid == True: print(“Wrong”) Instead of binding a lambda function to an identifier, use a generic function.
Because assigning lambda function to an identifier defeats its purpose.
And it will be easier for tracebacks # Prefer this def func(x): return None # Over this func = lambda x: x**2 When you are catching exceptions, name the exception you are catching.
Do not just use a bare except.
This will make sure that the exception block does not disguise other exceptions by KeyboardInterrupt exception when you are trying to interrupt the execution try: x = 1/0 except ZeroDivisionError: print(Cannot divide by zero) Be consistent with your return statements.
That is to say, either all return statements in a function should return an expression or none of them should.
Also, if a return statement is not returning any value, return None instead of nothing at all # 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 If you are trying to check prefixes or suffixes in a string, use ”.
startswith() and ”.
endswith() instead of string slicing.
These are much cleaner and less prone to errors # Correct if name.
endswith(and): print(Great!) End Notes 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! You can also read this article on our Mobile APP Related Articles (adsbygoogle = window.
adsbygoogle || []).
push({});.