This document gives coding convention used by team SONIA for python modules
By using PEP 8 coding standard, we believe that our python code readability will be improved. It is in our interest to develop our module by keeping in mind that readability is the key to an easy understanding of our code. By keeping readability in mind, we make sure that it is easy to integrate new team members and it is also easy to work back on previously developed modules.
This page is adding on existing python coding standard. The following links are exhaustive on the topic :
Explicit is better than implicit [1] : We encourage our members to use meaningful name for their functions, variables and classes. By using meaningful name, we increase code readability and comprehension.
class Car:
def __init__(self, brand, model, color):
self.br = brand
self.mo = model
self.col = color
class Car:
def __init__(self, brand, model, color):
self.brand = brand
self.model = model
self.color = color
You can easily see that is easier to understand the context of the object car when using meaningful variables.
Reading previously written either yours or others can be a pain. Following motto Beautiful is better than ugly [1]: We are recommending surrounding top-level functions and classes with two blank lines and surrounding method in class with one blank line. A blank line inside functions to ease up code understanding.
PEP 8 standard recommends 79 characters per line but we are currently recommending using maximum 100 characters per line.
Indentation is critical in python since if the code is not properly indented errors will be raised on code interpretation. The PEP 8 standard recommends the use of 4 consecutive space to indicate indentation, prefer spaces over tabs.
Our comments should be used to document the code to ease up understanding while reworking existing codes and ease up our team’s understanding of it. Code should explain itself by reading it but sometimes comments are required. keep in mind that If the implementation is hard to explain, it's a bad idea [1]
Python single line comments are hashtag (#)
# This is a single line comment
a = 1 + 2
Python multiple line (block) comment are using (""") repeated twice.
"""
This is a line comment
This is other line
"""
a = 1 + 2
Linter analyze code and flag errors that are present in the code, they also provide suggestions on fixes that could be done. Depending on your IDE or Code editor different linters are available we suggest using pylint
Autoformater are programs that autoformate your code to be conformed to PEP8 automatically. Black is an auto formatter that we suggest using.
[1] See Zen of Python.