Consider moving `.h` files to the same directory as their implementation source files

[rfairley]

Describe the feature Have include files kept in the same directory as the source file(s) that implement them. Specifically, every .h file currently in Common/include is moved to hardware, app, component, ... as needed. New directories are created if needed, e.g. mock for the Mock*.h files.

Reason for request As our project grows, our header files land in one directory, which has filled up fast. Although it isn't too hard to navigate, I think it's a bit more scrolling than is needed to locate a header file. Personally, I find it convenient to already have the directory to the source file already open, if I was looking at the header and need to navigate to the source.

Splitting the headers out would also make it easier to identify reusable components, such as UartInterface. Any interfaces would live in Common/interface.

As an example of another project, betaflight does this with headers.

The HAL drivers we use do have a single directory for include files, but I think this makes sense with HAL being a public library.

The directory Common could become the only include path (for our code), and we specify the subdirectory when including headers. This would look like: #include "mock/MockUartInterface.h" or #include "component/UartDriver/UartDriver.h". I think this expresses what the kind of thing being included is, from the source file.

Timeline No particular timeline.

[rfairley]

Decision:

• keep Common/include around just in case for now
• have Common/ hardware, mock, interface, component, test, app

later to do (after this issue):

• move test files next to their components
• have a Common.h or something similar to give a hierarchy of includes

[rfairley]

Thinking of the hierarchy of includes, since we will have namespaces for components determined by related module e.g. ::uart , ::udp, ::imu, ::dynamixel, we could have something like Common/component/inc/uart.h, Common/component/Inc/udp.h, and so on. For the uart case, this would look like:

Common/component/Inc/uart.h

#include "component/UartDriver/UartDriver.h"
#include "component/CircularDmaBuffer/CircularDmaBuffer.h"

(once header files are moved into the same directory as the source files (#170))

Common/app/ClientCodeWhichUsesUartDriver.h

#include "component/Inc/uart.h"

using uart::UartDriver;

[rfairley]

Possible idea: convention of specifying a more specific include path e.g. component/UartDriver/UartDriver.h from application-specific files only, and from component files only specify e.g. UartDriver.h. This keeps components more generic and gives application files some order by specifying component, interface, app, etc. in the include path.