Dev

Documentation

• Always consider how the code will be read and maintained by other engineers potentially years from now, and write code that is as clear and self-explanatory as possible without relying on comments or external documentation to explain non-obvious code.

Encapsulation

• Separate concerns and prefer to write modular code that is organized into functions, classes, and modules that have clear responsibilities and interfaces. Avoid writing monolithic code that is difficult to understand and maintain.
• Generally, prefer composition over inheritance, and prefer to use inheritance only when it is necessary and appropriate for the problem at hand.

Testing

• Avoid mocking functionality and prefer to write tests that test the actual functionality of the code. If mocking is necessary, prefer to mock as little as possible.
• Avoid writing unnecessary tests (e.g. tests of structure where a type system exists); prefer tests of functionality and behavior.

Python

• Adhere to the PEP 8 style guide for Python code where possible
• Prefer adding type hints
• Prefer as general typing as possible for input parameters, and as specific typing as possible for return types
  • For example, if a function just needs an iterable parameter, use Iterable instead of list or set. And if a function returns a list of strings, use list[str] instead of list[Any]
• Avoid use of linting/formatting ignores, casting types, or annoting with the Any type.