Table of Contents
Software Engineering Guidelines
Unit Tests
In case of a handover, unit tests should be run at least(!) twice a day:
(1) when you start your day to check that nothing is broken and you can continue with your tasks
(2) with a buffer before you end your day, to ensure that your changes did not break anything
Separate API tests for ordinary unit tests because API tests require a running container. The idea is to use pytest ./tests fully automated and the other tests 'staged' to ensure the container is running.
Skeletons
Whenever you copy & paste code / files from other (git) projects check that the headers and doc strings are correct and also check for unused imports.
Repositories
Always provide a
.dockerignore
and a
.gitignore
file to avoid that either unused data is sent to the docker daemon and/or that unwanted files in the repo are marked as untracked.
And always provide a requirements.txt
Scripts
Should use argparse to avoid magic constants and fixed paths. Furthermore, there should be at least one summary print statement what happened and likely where.
FastAPI
Each endpoint should minimal logging to summarize the results. Additionally a timing information is likely useful for debugging, but also to evaluate the performance of expensive calls.
Classes
Instantiated objects that live for a long time, like the ones in app_startup for FastAPI, should have a log message in init to summarize the state. And log messages in member functions allow easier debugging.
Code
Use TODO / / XXX to indicate code that needs to be changed. TODO has a lower priority. Those 'flags' are marked by most IDEs / Editors.
Monitoring
A new service should be added to the 'v5 slack alerts' by using the /health endpoint.