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

MARO uses isort and black to automatically format code, and uses flake8 and editorconfig-checker to check code:

isort . --settings-path .github/linters/pyproject.toml
black . --config .github/linters/pyproject.toml
flake8 . --config .github/linters/tox.ini
# PATH: Directory or file path of your changes.
editorconfig-checker --config .editorconfig PATH

It is worthy to notice that black will try to collapse multiple lines into one when possible. If you want to leave the code as what it is, you could use "magic trailing comma" to interact with black. Please see Black's documentation for details.

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.