# Design Principles

If you're developing your own routines, feel free to ignore any and all of these points.

If you're trying to understand how the library was designed or to push changes back to `master`, the following design principles apply.

1. Every function and class should have a triple quoted doc string
```
def function(input_a, input_b: str) -> int:
   """
   Short description of functionality (max 1 line)
   
   Longer description of how the algorithm works,
   what it's useful for, and if there are edge
   cases where it doesn't apply.

   input_a: the type of the input, and what it represents
   input_b: you can also use [type-hints](https://docs.python.org/3/library/typing.html), but note that these aren't enforced at run-time
   return: the type of the function returns (again, you can use type-hints)
   """
   return input_a + int(input_b)
```

2. Aim to test every line of the library with multiple examples. **Merge requests that add lots of untested code should not be merged**. You can learn more about testing in [Testing with Pytest](testing-with-pytest)

3. Jupyter notebooks should be used first-and-foremost as an interface *only*, and not for defining functionality. Large functions should be moved to the `torx` library where they can be reused and tested. One exception is plotting routines which often cannot be easily generalised.

4. Use Jupyter notebooks for examples/documentation. If you have developed a new use-case for the library, add a notebook showing how to perform and interpret the analysis. Notebooks can contain markdown sections: use these!

5. For functions which are specialized to a single code (i.e. grillix or gene-x), put these in `specializations`.

6. Try to write routines which are as flexible as possible. If you only need a single array from a data construct, it's best to pass the array rather than the whole construct since it makes it easier for others to use your class.

7. Use run-time checking for everything that isn't performance-critical. Use `assert` often, and check types with `isinstance`. It's easier to debug code which fails quickly.

8. Refactor frequently and aggressively. If you don't understand or like a particular bit of code, rewrite it, or delete it. If some functionality is no longer used, delete it. No functionality is above review or revision.