diff --git a/CppCoreGuidelines.md b/CppCoreGuidelines.md index f96aa6311..1f84394c9 100644 --- a/CppCoreGuidelines.md +++ b/CppCoreGuidelines.md @@ -19208,6 +19208,7 @@ Source file rule summary: * [SF.10: Avoid dependencies on implicitly `#include`d names](#Rs-implicit) * [SF.11: Header files should be self-contained](#Rs-contained) * [SF.12: Prefer the quoted form of `#include` for files relative to the including file and the angle bracket form everywhere else](#Rs-incform) +* [SF.13: Use portable header identifiers in `#include` statements](#Rs-portable-header-id) * [SF.20: Use `namespace`s to express logical structure](#Rs-namespace) * [SF.21: Don't use an unnamed (anonymous) namespace in a header](#Rs-unnamed) @@ -19618,7 +19619,7 @@ Nevertheless, the guidance is to use the quoted form for including files that ex #include // From the standard library, requires the <> form #include // A file that is not locally relative, included from another library; use the <> form #include "foo.h" // A file locally relative to foo.cpp in the same project, use the "" form - #include "foo_utils/utils.h" // A file locally relative to foo.cpp in the same project, use the "" form + #include "util/util.h" // A file locally relative to foo.cpp in the same project, use the "" form #include // A file in the same project located via a search path, use the <> form ##### Note @@ -19631,6 +19632,34 @@ Library creators should put their headers in a folder and have clients include t A test should identify whether headers referenced via `""` could be referenced with `<>`. +### SF.13: Use portable header identifiers in `#include` statements + +##### Reason + +The [standard](http://eel.is/c++draft/cpp.include) does not specify how compilers uniquely locate headers from an identifier in an `#include` directive, nor does it specify what constitutes uniqueness. For example, whether the implementation considers the identifiers to be case-sensitive, or whether the identifiers are file system paths to a header file, and if so, how a hierarchical file system path is delimited. + +To maximize the portability of `#include` directives across compilers, guidance is to: + +* use case-sensitivity for the header identifier, matching how the header is defined by the standard, specification, implementation, or file that provides the header. +* when the header identifier is a hierarchical file path, use forward-slash `/` to delimit path components as this is the most widely-accepted path-delimiting character. + +##### Example + + // good examples + #include + #include + #include "util/util.h" + + // bad examples + #include // bad: the standard library defines a header identified as , not + #include // bad: the standard library defines a header identified as , not + #include "Util/Util.H" // bad: the header file exists on the file system as "util/util.h" + #include "util\util.h" // bad: may not work if the implementation interprets `\u` as an escape sequence, or where '\' is not a valid path separator + +##### Enforcement + +It is only possible to enforce on implementations where header identifiers are case-sensitive and which only support `/` as a file path delimiter. + ### SF.20: Use `namespace`s to express logical structure ##### Reason