Cerc Python Style Guide

What's coding style and why it matters

Coding style is just how the code looks, it's incredibly personal, and everyone has their style.

Your preferred architectures, variable and function naming style all of then impacts in your code style and how the others read and understand it, so it could become a significant burden if everyone is coding on his own.

At CERC we are following the PEP8 with two spaces indentation instead of four.

Tools.

We use PyCharm as an integrated development environment and follow the tool's overall advice but the space indentation, which we set to two spaces instead of default four spaces.

For code analysis, we enforce the usage of pylint with our own custom style definition

Naming convention

Name your folders and files in lowercase.
Your class names must start in capital letters and follow the python CapWords pattern.
Methods and properties that return lists must end in "s".
Methods and variables should be lowercase and use _ (underscore) as word separator.
Constants names must be all capitals.
Avoid the usage of "get_" and "set_" methods whenever possible, by using @property and @variable.setter decorators instead.
"Private" methods, variables and properties start with _ (underscore)

Imports

All the imports should be defined at the top of the file after the license and contact information comment

"""
MyClass module
SPDX - License - Identifier: LGPL - 3.0 - or -later
Copyright © 2020 Project Author name name@concordia.ca
"""

import sys

Ensure that your imports are used and remove any unused.

Object attributes and methods

Use properties whenever possible and encapsulate the access to all the calculated object attributes into a properties as shown in the following example.


  @property
  def object_attribute(self):
    if self._object_attribute is None:
      self._object_attribute = ...
      ...
    return self._object_attribute

or if the property can be modified like in the following example


  @property
  def object_changeable_attribute(self):    
    return self._object_changeable_attribute       
    
  @object_changeable_attribute.setter
  def object_changeable_attribute(self, value):
    self._object_changeable_attribute = value

If your method or attribute returns a complex object use type hints as in this example


  @property
  def complex_object(self) -> ComplexObject:    
    return self._object_changeable_attribute       
    
  def new_complex_object(self, first_param, second_param) -> ComplexObject:
    return ComplexObject(first_param, second_param, self.property)

always access your variable throught the method and avoid to access directly.


  @property
  def object_attribute(self):    
    return self._object_attribute       
    
  def operation(self, first_param, second_param):
    return self.object_attribute * 2

Attributes with known units should be explicit in method's names


  @property
  def distance_m(self):    
    return self._distance

Coments

code documentation

all public classes, properties and methods must have code comments


  class MyClass
  """
  MyClass class perform models class operations
  """
  
  def __init__(self):
  
  
  @property
  def object_attribute(self):   
    """
    My class object attribute
    :return: int
    """
    return self._object_attribute       
    
  def operation(self, first_param, second_param):
    """
    multiplies object_attribute by two
    :return: int
    """
    return self.object_attribute * 2

To do's

Pending to implement operations should be indicated with ToDo comments to highlight the missing operation

  # ToDo: right now extracted at city level, in the future should be extracted also at building level if exist

3.9 KiB Raw Blame History