• Rahul Agrawal

PEP8



What is PEP8


Python Enhancement Proposal 8, or PEP 8, is a style guide for Python code which was developed and defined by Guido van Rossum, Barry Warsaw, and Nick Coghlan in 2001. It helps python programmers to write consistent and readable code. it is not mandatory to follow but it is a good practice in the programming world. PEP8 involves rules/conventions for variable names, whitespace, inline comments, indentation, and much more. It has great resources to write clear, consistent, and readable code. It also portrays one's ability to write code as "most of peoples can code but very few of them can code that others also can understand "



Why use PEP 8?


“code is read much more often than it is written”, According to Guido van Rossum, the author of Python. Coding is mostly done in a collaborative environment so that code has to be analyzed by multiple times by multiple users and programmers so that it becomes mandatory to write code in such a way that any person can read and understand the code easily and with less effort to improve code reusability . So it is the programmer's tasks to write code by following some rules and best practices. It will take time to write code in well-documented form rather than messy form, but it will be worth it anytime. So that’s why we regularly follow coding conventions. Every language has its own rules and practices defined by experts, creators, and developers . From my personal experiences , code gets messy when it evolves so to understand code at later stages , it should be written and documented in a way that , it will be globally acceptable and easily human-readable.


# Normal Code of some programmers


# Well Documented code by following best practices


PEP8 Conventions


Coding Order

Python code must follow the order which is mentioned in PEP8 so to increase code readability, Also it will make modification easier at the TOP of the code always have a docstring (“”” “””) , docstring contains metadata about code like Author name, Author contact details, Module purpose, Offered functionalities, etc. Docstring always starts and ends with 3 double quotes (“””)



"""
Author: Rahul Agrawal
Github: https://github.com/rahul-agrawal-99
Module: PEP8-Example
Functions: PEP8-conventions, PEP8-Details
"""


After Docstring, the Import Statement Should be there. In PEP8, some rules define the writing of import statements.

Following are some tips to write import statements : multiple modules from 1 package can be imported on single line code Use different import statements for 2 distinct packages Try to be specific that only needy functionalities from the package should be imported Also, try to mention why you are requiring the library that is getting imported.



# Allowed
 
import numpy as np    
from pandas import read_csv , read_excel  
 
# Not allowed
 
from os import *    
import os, sys    
 

After the Import statement, try to write Constants that will be used later by any of the Functionalities. use only UpperCasing for naming constants.



PIE = 3.1472
ACCESS_POINT = "http://my-url.co/"
PORT = "8080"
SECREAT_PASSWORD = "secret"  


After 2 - 3 black lines, write actual code and functionalities



"""
Author: Rahul Agrawal
Github: https://github.com/rahul-agrawal-99
Module: PEP8-Example
Functions: PEP8-conventions , PEP8-Details
"""
 
import numpy as np      # For mathematical operations
from pandas import read_csv , read_excel   # reading CSV and excel files for data 
 
PIE = 3.1472
ACCESS_POINT = "http://my-url.co/"
PORT = "8080"
SECREAT_PASSWORD = "secret"  
 
 
# Actual code starts here


Naming Conventions

Choosing names for your variables, functions, methods, etc. is not always simple. It's critical to think carefully about the names you select to make sure they are understandable, pertinent, and practical. To make the meaning of an object crystal apparent, we advise adopting descriptive names. You will benefit both now and later if you choose descriptive names. If you give one of your functions a hazy name, you risk forgetting what it does when you revisit your code in a few days or weeks. This is where PEP 8 is useful.

Naming in Python should be well defined as per functionality so that code readers can understand the meaning and use of variable, class, or function.


1. For Class

Use camelcase or capitalized words for the class name. Avoid the use of underscores to separate words CamelCase is a style of word separation that does not use spaces and capitalize the first letter of each word in a sentence like CamelCase , LikeMe etc.


# Allowed 
class MyClass():
 	pass
 
# Not allowed 
class myclass():         # also my_class or myClass
	pass 


2. For Variables

There can be multiple types of variables such as a class object, constants, and data structure names. The naming of variables involves:

  • Use lowercase single letter or word

  • If contains more than 1 word then use “_” to separate 2 lower cased words

  • Do not use capitalized/Uppercased word unless it is actually constant

  • Try to name variables as per their functionality such as the list of prime integers that can be named as prime_list

Almost all the variable has the same convention but there are also some exception like, in constant naming, it should be always uppercased



# Allowed 

list_prime = []

COLOR_WHITE = (255,255,255)

new_date  = Date()

x  = 20

# Not Allowed 

Mylist  = []

list123 = []



3. For Methods / Functions

Following are some guidelines for Function or method naming

  • Always name should be lower cased

  • Use of “_” allowed to join 2 different words

  • Avoid use of in built methods of python

  • Use of “_” at beginning is allowed only in class methods like __init__



# Allowed

def fun_add():
	pass 

class MyClass():

    def  __fun_read():   # private functions
		Pass


4. For Module and packages

Following are some guidelines for module and package naming

  • Naming should be short as possible

  • Use of “_” is allowed to join 2 words except in package naming

  • Use only lowercase words



# Allowed 

my-module  , module_1

# Not Allowed

Module , Module_for_so_so_funtion




PEP 8 Coding Structure


WhiteSpaces

Spacing between 2 characters is a way to make code easy to read, that's why it is important to follow correct spacing, it should not be too much or too less.


Spacing for variable and value


# right way
X = 10     # keep one black space from both side
Mylist = [1, 2, 3]   # value +,+ 1 whitespace + next value    and so on

#  Wrong way 
X=10  or  X =   10
Mylist = [1,2,3,   4]


Spacing between operator and operands


# right way
i = i + 1   # keep 1 blank space in between
i += 1 
x = x*2 + 1   # for multiply/divide keep both operands together
y = (a+b)    # if operation is in brackets , then dont keep blank spaces
 
 
#  Wrong way
i=i+1
i +=1
c = c * 2     or  c = c* 2
x = (a + b)


Line length, Line break And Indentation

For List :


li = [      # use if list has multiple list inside
    [ ],
    [ ]
]
    

For Dictionary :


 # always write dictionary as this
dictionary = {       
    "key" : "value",
}


For Conditional Statements:


#  In IF statements
 
# Correct:
if foo == 'blah':
    do_blah_thing()
 
# Wrong:
if foo == 'blah': do_blah_thing()


For Function :


 # one blank space between arguments, also keep return type whenever possible
def fun(a, b) -> int:     
return fun(a=a+1 ,b=b-1)   


# at max 79 char as last one is newline character
def myfun(arg1,arg1,arg1,arg1,arg1,arg1,arg1,arg1,arg1,arg1,
       arg1,arg1,arg1,arg1,arg1,arg1): 
       # use newline for extra arguments with 4 indention tabs left
 	mycode = none           # code should be start from 2 indention tabs
       

For Class and its methods :


class A():
   pass
# 1
# 2             , exact 2 black new line spaces before declaring a class or any function
class B():    
 def __init__(self):
   pass
# 1 blank line between methods of a class  
 def __repr__(self):
   pass


Comments

Comments play an important role in the coding process. It is critical that they are clear, up to date, and useful. Comments not only help us, but they also help anyone else who comes into contact with our code. It's best to write comments in full sentences, with the first letter of the first word capitalized. This is known as a sentence-style case. It's fine to use a lowercase letter here if our code starts with an identifier. We should never, ever change the name of an identifier.



def func():
	# comment also should be indented inside class or function
	pass

var = 10  # keep 2 to 5 whitespaces between value and # sign

“”” in case of docstring start from the first line
End line here so that the last 3 quotes should be always on a new line
”””


Return Statements

Consistent in return , always statement should return something (except None type) irrespective of any condition:


# Correct:
 
def foo(x):
    if x >= 0:
        return math.sqrt(x)
    else:
        return False
 
# Wrong:
 
def foo(x):
    if x >= 0:
        return math.sqrt(x)
    

Exception Handling

try:
  # mycode
# explicitely mention possibly occuring error instead using Exception as e 
except ImportError:     
  #  handling
except Exception:
  #  final handle for rare exception happened



Auto Formatting Tools


Linters are Auto Formatting programs that provide feedback on the quality of code by displaying warnings and errors. They can detect Python code errors, invalid code patterns, and elements that do not adhere to your conventions. Python linters have several advantages, including:

  • Bug prevention in a project.

  • Making Python code readable for any programmer.

  • Detecting and removing unnecessary code.

  • Making code more readable and less complex.

Of course, every approach has drawbacks:

  • Linters can produce false positive results.

  • This procedure can take some time.

  • Some mistakes may go unnoticed.


List Of some Available Auto-formatters in Python :


Black

Black is the uncompromising Python code formatter. You give up control of the finer points of hand-formatting by employing it. You receive speed, determinism, and independence from pycodestyle's pestering about formatting in exchange for Black.


pip install black


autopep8

Autopep8 would auto-format your python script. not only the code indentation but also other coding spacing styles. It makes your python script to conform the PEP8 Style Guide.


pip install autopep8


yapf

Most of the current formatters for Python --- e.g., autopep8, and pep8ify --- are made to remove lint errors from code. This has some obvious limitations. For instance, code that conforms to the PEP 8 guidelines may not be reformatted. But it doesn't mean that the code looks good.

YAPF takes a different approach. It's based off of 'clang-format', developed by Daniel Jasper. In essence, the algorithm takes the code and reformats it to the best formatting that conforms to the style guide, even if the original code didn't violate the style guide. The idea is also similar to the 'gofmt' tool for the Go programming language: end all holy wars about formatting - if the whole codebase of a project is simply piped through YAPF whenever modifications are made, the style remains consistent throughout the project and there's no point arguing about style in every code review.


pip install yapf



Wrapping Up , Reading and writing code are much more effective and efficient thanks to the PEP 8 style standard. A guide is a helpful tool that we can use to improve our code reading and writing processes even though it might not always be applicable to our line of work. There is still a lot to learn about PEP 8, which we only touched on briefly in this article.
Enjoy Learning 😄📖💻









13 views0 comments

Recent Posts

See All