Code Style Guide

Extension Recommendation

VSCode

If your working IDE is VSCode, we recommend you to install and use these extensions:

• Code Spell Checker: Check the spelling of your code and help you fix the typo in time.
• EditorConfig for VS Code: Automatically fix formatting issues according to the .editorconfig file when saving.
• Trailing Spaces: Automatically remove the unwanted trailing spaces when saving.

Auto-formatting Scripts

isort --setting-path .github/linters/tox.ini

flake8 --config .github/linters/tox.ini

# PATH: Directory or file path of your changes.
editorconfig-checker --config .editorconfig PATH

Python Style

Generally speaking, we follow Google Python Style Guide, and the differences/highlights are the below points:

• Line length: maximum line length is 120 characters.
• Comments: never mix code and comment in one line.
• Parameter list: use type declaration as much as you can.
• Function call: use keyword arguments.
• String format: use " if you can, use f-Strings.
• Log: use maro.utils.logger.
• Exception: define them in maro.utils.exception.
• Docstring for class/function.
  • Definition of class/function.
  • Arguments explanation.
  • Returns explanation.

class XxxYyyZzz():
    """Summary of the class here.

    Details.

    Attributes:
        public_attribute_1: Introduction of this attribute.
        public_attribute_2: ...
        ...
    """

    def __init___(self, quota: int, is_test: bool):
        """One line summary.
        
        Details.

        Args:
            quota (int): Details.
                E.g. ...
            is_test (bool): Details.
            ...     
        """
        pass

    def run(self, para1: int, para2: bool = True):
        """One line summary.

        Details.

        Args:
            para1 (int): Details.
            para2 (bool): Details. Defaults to True.

        Returns:
            type: Details.
        """
        pass

• Naming

  • File naming: xxx_yyy_zzz.py (noun structure)
    • Abstract class file naming: abs_xxx_yyy.py
  • Class naming: XxxYyyZzz (noun structure)
    • Abstract class naming: AbsXxxYyy
  • Function naming: verb/verb + noun
    • Private function: _xxx_yyy
    • Public function: xxx_yyy

• Import

  • Import blocks order: native lib, 3rd party lib, privative lib.
  • In each import block, package are listed in alphabet order.
  • Between blocks, a blank line is needed.

  import io
  import os
  
  import numpy as np
  import pandas as pd
  
  from maro.backends.frame import FrameBase
  from maro.event_buffer import EventBuffer

• File format: LF.