Code Conventions

Python conventions

Follow PEP 8.

We use the flake8 linter to enforce style rules. This greatly simplifies code reviews.

Exceptions:

• We use 99 characters as the maximum line length.
• Use spaces around = signs in default parameter values in functions with annotations:

def f(x: int = 1) -> None: ...  # OK, since f is annotated

def f(x=1) -> None: ...         # OK, fall back to PEP 8 if there is no annotation

Features to avoid

It's usually better to avoid these Python features (at least in performance-sensitive code):

• getattr, setattr
  • Mypy can't type check these calls properly
  • These get compiled into slow dynamic attribute gets/sets by mypyc
• functools
  • Type checking is sometimes limited, resulting in Any types
  • Mypyc, our compiler, often generates better code if these are replaced with more "primitive" / lower level Python code
• copy.deepcopy
  • This may be dangerous with objects with complex state such as caches (we might also add such state later)
  • Performance can be hard to predict
  • This can cause problems in code compiled with mypyc
• Metaclasses
  • Mypyc, our compiler, generates less efficient code for metaclasses
  • Type checking may be limited
  • Metaclasses can make code harder to understand