4

Suppose I'm writing a library named foo, in C++. When installed to /some/where, it presents include files in /some/where/include/foo, and I expect the user to compile with -I/some/where/include.

Suppose foo has header files foo/first.hpp, foo/second.hpp and foo/bar/third.hpp (and they have these relative locations both before and after installation).

Now, within these files, when including other foo header files, should I...

  1. Always use angle brackets, in line with my assumption stated above? e.g. 
    #include <foo/second.hpp>
#include <foo/bar/third.hpp>
  2. Never use angle brackets, e.g. 
    #include "second.hpp"
#include "bar/third.hpp"
    or 
    #include "../first.hpp"
  3. Use angle brackets in some cases, and quotes otherwise?

I've noticed that Boost seems to take approach (1.), and I like it, because it clarifies these include files are part of the foo library. However, the accepted answer to this SO question suggests approach (2.) (albeit for the C language).

The C++ coding guideline SF.12 is actually somewhat ambiguous about this matter. On the one hand, it says:

use the quoted form for including files that exist at a relative path to the file containing the #include statement (from within the same component or project) and to use the angle bracket form everywhere else

but then also

Library creators should put their headers in a folder and have clients include those files using the relative path #include <some_library/common.h>

but the library is also a client of its own include files; and if you've put the headers in a library-specific folder, then perhaps this rule applies (as the rationale for the earlier rule does not seem to hold when a library-specific folder is used).

einpoklum
  • 118,144
  • 57
  • 340
  • 684
  • 3
    It depends. Are you doing the `#include` in a header file that is supposed to be installed? Will the relative path between the header files be the same? And will both `<>` and `""` work? Then pick whichever you want. Otherwise I *personally* tend to use `""` for local and private header files. – Some programmer dude Oct 05 '22 at 19:09
  • The difference is what paths your compiler will search in order to find the header, so it depends on what you want – Jesper Juhl Oct 05 '22 at 19:22
  • Are you absolutely sure the user of your lib specifies the correct include path? If you've installed the headers in `/foo/bar/include/some_library/common.h` and the user compiles with `-I/foo/bar` and uses `#include "include/some_library/common.h"` they'll get compiler errors, if you don't use relative paths. If you're worried about readability: I usually group includes by libs and separate those by blank lines. You could even add a comment `// some_library includes`... – fabian Oct 05 '22 at 19:23
  • @Someprogrammerdude: Naturally, if files are supposed to be installed and their locations after installation changes, I would need to account for that. Clarified the question to indicate that is not the case. Also, yes, both "" and <> work - otherwise I would have no dilemma. – einpoklum Oct 05 '22 at 19:36
  • @JesperJuhl: Expect for the unlikely circumstance of another library using the same include subdirectory, the compiler will find the same files regardless of the path it searches. – einpoklum Oct 05 '22 at 19:38
  • @fabian: Well, maybe it's a good idea for them to get the compiler error "early" rather than through some subtle breakage. – einpoklum Oct 05 '22 at 19:40
  • Angle brackets are for system headers; quotes are for include files. Note the difference in the nouns: headers don't have to be files (although they in fact always are); the compiler is allowed to "know about" them. The rule is that quoted names are treated as file names and searched in an implementation-defined manner. Names in angle brackets are looked up in an implementation-defined manner, and if not found, they are then looked up as if they were in quotes. – Pete Becker Oct 05 '22 at 20:57
  • @PeteBecker: 1. Even "files" don't have to be files; see [lex.separate] in the C++ standard (e.g. as quoted [here](https://stackoverflow.com/a/57548515/1593077)). 2. System headers are simply those headers found in directories you've told the compiler about (e.g. with `-I` or `-isystem`). So, in my case, I _am_ including system headers. – einpoklum Oct 05 '22 at 21:03
  • Is the ambiguity of SF.12 resolved by [this SO answer](https://stackoverflow.com/a/72065059/5534993) respectively [that referenced GitHub comment](https://github.com/isocpp/CppCoreGuidelines/pull/1596#issuecomment-1113901271)? – user5534993 May 02 '23 at 13:26

0 Answers0