Source files
SF.13
Use portable header identifiers in `#include` statements
Reason
The standard 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 <vector>
#include <string>
#include "util/util.h"
// bad examples
#include <VECTOR> // bad: the standard library defines a header identified as <vector>, not <VECTOR>
#include <String> // bad: the standard library defines a header identified as <string>, not <String>
#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.