Mirrors/CppCoreGuidelines
1
0
Fork 0
mirror of https://github.com/isocpp/CppCoreGuidelines.git synced 2025-12-18 13:14:40 +03:00
Code Issues Actions Packages Projects Releases Wiki Activity

Update wording and examples for SF.12: Prefer the quoted form of #include for files relative

Browse Source 
Updated wording, adjusted example, and provided a more verbose example of what can go wrong if using the wrong form.
This commit is contained in:
apenn-msft
2020-04-03 13:01:07 -07:00
committed by GitHub
parent e47463c14a
commit 66792e4875
1 changed files with 7 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
CppCoreGuidelines.md
View File

@@ -19190,17 +19190,17 @@ The [standard](http://eel.is/c++draft/cpp.include) provides flexibility for comp
the two forms of `#include` selected using the angle (`<>`) or quoted (`""`) syntax. Vendors take
advantage of this and use different search algorithms and methods for specifying the include path.
Nevertheless, the guidance is to use quoted form for including files that exist at a relative path to the file containing the #include statement and to use the angle bracket form everywhere else where possible. This supports being clear about the locality of the header relative to files that includes it or in scenarios where the different search algorithm is required. For example, it makes it easy to determine at a glance whether a header is being included from a local relative file versus a standard library header or an external header from another project.
Nevertheless, the guidance is to use the quoted form for including files that exist at a relative path to the file containing the '#include statement' and to use the angle bracket form everywhere else, where possible. This encourages being clear about the locality of the header relative to files that include it, or scenarios where the different search algorithm is required. For example, it makes it easy to understand at a glance whether a header is being included from a local relative file versus a standard library header or an external header from another project.
##### Example
foo.cpp:
#include <string> // From the standard library, required form
#include <some_library/common.h> //A non-local include file from an external library, use the <> form
#include "foo.h" // A local file relative to foo.cpp, use "" form
#include "utils/foo_utils.h" // A local file relative to foo.cpp, use "" form
// foo.cpp:
#include <string> // From the standard library, requires the <> form
#include <some_library/common.h> // A file that is not locally relative, included from an external project; use the <> form
#include "foo.h" // A file locally relative to foo.cpp, use the "" form
#include "foo_utils/utils.h" // A file locally relative to foo.cpp, use "" form
##### Note
Failing to follow this results in difficult to diagnose errors due to picking up the wrong file by incorrectly specifying the scope when it is included.
Failing to follow this results in difficult to diagnose errors due to picking up the wrong file by incorrectly specifying the scope when it is included. For example, in a typical case where the '#include ""' search algorithm may search for a file existing at a local relative path first, then using this form to refer to a file that is not locally relative could mean that if a file ever comes into existence at the local relative path (e.g. the including file is moved to a new location), it will now be found ahead of the previous include file and the set of includes will have been changed in an unexpected way.
Library creators should put their headers in a folder and have clients include those files using the relative path `#include <some_library/common.h>`