Source code organization

The code base should contain all the source code, third-party libraries, data, scripts, and automations needed to build the final image. It is a good idea to keep self-contained libraries in separate directories, so that they can be easily updated to newer versions by replacing the subdirectory itself. Makefiles and other scripts can be placed in the project's root directory. Application code should be short and synthetic, and access the modules abstracting the macro functionalities. Functional modules should describe a process while hiding the details of the underlying implementation, such as reading data from a sensor after it has been properly sampled and processed. Aiming for small, self-contained, and adequately abstracted modules also makes the components of the architecture easier to test. Keeping the majority of the logic for the application components separated from their hardware-specific implementation improves portability across different platforms, and allows us to change the peripherals and the interfaces used on the target even during the development phase. Abstracting too much, though, impacts costs, in terms of development effort and resources needed, so the right balance should be researched.