Clarify include style when headers are in the same folder as the including file

[fruffy]

This came up in #5006 (comment)_

If we have the following two files:

dir
|- file.cpp
|- file.h

How should file.cpp include file.h
Using the project-absolute path: #include "dir/file.h" or just #include "file.h"?

We currently have a mix of these in the compiler. I am partial to the project-absolute path but not opposed to the relative style. If we go with one option we should add a linter or tool to fix these paths and make them consistent.

[asl]

I would say the rule might be the following:

• If the header is expected to be the part of API, then it should be always used like #include "dir/file.h".
• Otherwise, if the header is local, then it should be included like #include "file.h"

Though, it is pretty hard to automatically determine if this is so. Then, maybe the rule should be as follows:

• The primary header for the file should be included like #include "file.h" only from within file.cpp
• Otherwise – always use #include "dir/file.h".

[fruffy]

I would say the rule might be the following:

* If the header is expected to be the part of API, then it should be always used like `#include "dir/file.h"`.

* Otherwise, if the header is local, then it should be included like #include "file.h"

Though, it is pretty hard to automatically determine if this is so. Then, maybe the rule should be as follows:

* The primary header for the file should be included like `#include "file.h"` only from within `file.cpp`

* Otherwise – always use `#include "dir/file.h"`.

Yeah, we do not really have a notion of API, which might be the reason why things are as they are.

At least for the second example, writing a tool could be easily doable. Maybe I can even generate this with ChatGPT :)