I am preparing for a discussion with my fellow programmers which will be about their use of the C/C++ `#include` directive. The codebase which I have to retrofit to Automotive standards is using includes of the form `#include <path/out/of/the/blue.h>`. To be precise: the projects carry around a large set of include paths for the compiler (`-Iinclude/me` etc.) BUT the path expressions even reach outside of these places so that `blue.h` can only be found if the compiler internally produces a combination of all include paths with the path in the statement itself: `include/me/`+`path/out/of/the/blue.h`. There are many gripes I have against this practice:

 - AFAIK `<>` is reserved for system headers coming from the platform, and are strongly discouraged to be used by project code. The compilation only works because the C and C++ standard requires the compiler to search again as if the file was given with `""` if it is not found on the first pass.
 - It creates a review nightmare: the include file is neither at the path rooted at the directory where the including C or C++ file sits nor is it in any of the include locations, you have to repeat the search of the compiler to eventually find it somewhere, yet at this point in time you aren't really trusting yourself - the compiler could have searched differently. 
 - There are a number of multiple file names in the project tree: `blue.h` can be found at a number of locations and sometimes one `blue.h` serves as a dispatcher file for the inclusion of a more specific, the true `blue.h` down the directory tree. Which `blue.h` is selected is distinguished by `#define PLATFORM` macros and the like.
 - It creates a monolithic, reorganization-resisting project structure, coupling C and C++ interfaces (which live in directory-less space as far as the language is concerned) with the file system. 
 - It spills over into new projects: As soon as one uses a header which itself includes other path-dependent headers, the new projects build script has to adapt to this usage.

We are using [mbed-os](https://www.mbed.com/en/platform/mbed-os/) and it looks like its source tree suffers from the same in (IMHO) bad code structuring choice.

As a TL;DR one could say that I have the firm belief that one is ill-advised to carry the project structure into the source code. One has to supply a lot of structure and dependencies to the build system and linker anyway - introducing a secondary coupling per the source files wreaks havoc at least when one tries to change the build system (as I am forced to now).

What is the public opinion on this? How flat or tree-like do you manage your includes?

PS: MISRA is only remotely talking about this issue though one could read it as "don't use anything else but header file names"

PPS: I am not completely against the use of paths (well, I am in my code, but I could live with this in inherited code) *as long as this isn't visible from the outside* but the current versions of the projects rather forces one to adapt to exactly this usage.