Relative include paths in headers

[CuriousGeorgiy]

Maintenance Challenges:
As the project grows and evolves, the directory structure may change. If there are numerous relative paths scattered throughout the codebase, we will need to update each occurrence whenever structural changes are made. This can be error-prone and time-consuming.

Readability and Maintainability:
Relative paths in include statements can make the codebase less readable and harder to maintain. They make it less clear where the included files are located in relation to the current source file, which can be confusing for both you and others who work on the code.

Non-standard Build Systems:
Considering the project is a library used as an external dependency by others, we need to keep in mind some build systems or development environments may not handle relative include paths well or may interpret them differently. This can lead to inconsistencies and issues when building the code in various contexts.

IDE and Tool Support:
Integrated development environments (IDEs) and code analysis tools may not handle relative paths effectively, potentially leading to incorrect code analysis or debugging.

User Perspective:
Considering the project is a library used as an external dependency, using relative paths has a higher chance of interfering with the user's codebase. Consider the following include path we have in the codebase: ../Utils/Logger.hpp. Consider the project structure a user can have:

.
├── CMakeLists.txt
├── third_party
│   ├── tntcxx
├── src
│   ├── include
|       ├── .......
|   ├── Utils
|       ├── Logger.hpp

If the user has a ./src/include path specified and it goes earlier in the include path list than the one provided by the subproject, the user's Utils/Logger.hpp file could get included instead of our header.

Other opinions:

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).¹

Relative paths rely on the current working directory. This is a form of global state, and as such it should be avoided whenever possible.

Depending on the structure of your application, the current working directory may not be guaranteed to be constant through all code paths that can reach a certain routine. It is also susceptible to change as a result of changes external to the code, such as a change in the way that URLs are interpreted by the web server by mechanisms such as URL rewriting. Relative paths can also be ambiguous in the context of static analysers, meaning that refactoring tools in IDEs can make mistakes and interpret the meaning of the path reference in unexpected ways.²

Relative includes paths with .. in it look a bit ugly and expect a certain filesystem structure, that is, "../../common/log.hpp" is two folders up. It makes sense to avoid unnecessary dependencies in general and on filesystem structure in particular, so that moving a header file from one directory to another does not force you to update all source files that include that header.³

Footnotes

1. https://softwareengineering.stackexchange.com/questions/407056/the-case-against-path-expressions-in-include-directives ↩

2. https://gist.github.com/DaveRandom/6830e379578a66e2c82593137e79d099#why-is-using-a-relative-path-generally-bad ↩

3. https://stackoverflow.com/a/5006955 ↩