Best Practices

This page illustrates the best practices used within orbital applications.

Code Organization

The following hierarchy is recommended:

  • <app_name> * clients/ - clients to external services, databases

    • client_name.py - should be named after the client itself.
    • lib/ - business logic lives here.
    • routes/ - APIs exposed.
    • tests

Test Code Organization

If the test is specific to one module, the test should live in a file that matches that module in path and name. For example, if testing a user client which should be located at app/clients/user.py, you would put your test in app/tests/clients/test_user.py.

Why Package Test Code with the Service?

There is a separate practice of moving tests into a directory separate from the application itself. This has a couple disadvantages:

  1. It is not possible to do relative imports.
  2. The test code is not deployed alongside the application code, so you are not able to quickly glance at unit tests to get a better understanding of how code is intended to be used.

Interface should be HTTP over JSON

For a majority of applications, the interface exposed should be HTTP over JSON. Although this is not a hard rule, standardizing around some common protocol ensures maximum tool sharing to faciliate these interactions.