From 9bbc02175ca1c50ce5fbb3498793935773b8640a Mon Sep 17 00:00:00 2001 From: Arthur O'Dwyer Date: Mon, 17 Aug 2020 11:07:37 -0400 Subject: [PATCH 1/2] Add linebreaks in paragraphs. NFC. --- CppCoreGuidelines.md | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/CppCoreGuidelines.md b/CppCoreGuidelines.md index f7c7a2e85..46ad86348 100644 --- a/CppCoreGuidelines.md +++ b/CppCoreGuidelines.md @@ -19296,7 +19296,13 @@ 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 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, where possible. This encourages being clear about the locality of the file relative to files that include it, or scenarios where the different search algorithm is required. 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 a header from the alternate search path (e.g. a header from another library or a common set of includes). +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 (from within the same component or project) and to use +the angle bracket form everywhere else, where possible. This encourages being clear about the locality +of the file relative to files that include it, or scenarios where the different search algorithm is +required. 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 a header from the alternate search path (e.g. a header +from another library or a common set of includes). ##### Example @@ -19309,9 +19315,15 @@ Nevertheless, the guidance is to use the quoted form for including files that ex ##### 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. For example, in a typical case where the `#include ""` search algorithm might 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. +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 might 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 ` +Library creators should put their headers in a folder and have clients include those files using the +relative path `#include ` ##### Enforcement From 640e10c6e6f3096a6ad1863045d3dc2cefbf75c7 Mon Sep 17 00:00:00 2001 From: Arthur O'Dwyer Date: Mon, 17 Aug 2020 11:11:23 -0400 Subject: [PATCH 2/2] SF.12: Rewrite to eliminate the notions of "project" and "component"; also copyedit. The major change here is simply to delete parentheticals that muddy the waters by talking about files belonging to "projects" or "components". My experience has been that in industry we have "codebases," which are sometimes split up into "repositories" and/or "libraries" (which may be installed in e.g. /usr/local/include or may be used straight from their source tree), and everyone works on everything or at least knows someone who works on the other thing. Figuring out what's "in the same project" and what's "in a different project" is often fuzzy. I would try to set up the build system so that its `target_include_directories` (or equivalent) could find every header via `<>`, and then use `<>` everywhere: even for files in the "same" component. (This does require that you follow SF.12's advice for "Library creators", though, which I admit I don't for just about all of my hobby projects.) Strangely, the "Enforcement" section seems to have been written by a `<>` partisan like me, even though the rule itself is `""`-endian. I copyedited the "Enforcement" section for grammar; did I unconsciously misinterpret what it was trying to say? What *was* it trying to say? Should it just be deleted? --- CppCoreGuidelines.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/CppCoreGuidelines.md b/CppCoreGuidelines.md index 46ad86348..9cc246f49 100644 --- a/CppCoreGuidelines.md +++ b/CppCoreGuidelines.md @@ -19297,37 +19297,37 @@ the two forms of `#include` selected using the angle (`<>`) or quoted (`""`) syn advantage of this and use different search algorithms and methods for specifying the include path. 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 (from within the same component or project) and to use +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 file relative to files that include it, or scenarios where the different search algorithm is -required. 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 a header from the alternate search path (e.g. a header -from another library or a common set of includes). +required. It makes it easy to understand at a glance whether a header is being included from a locally +relative file, versus a standard library header or a header from the header search path (e.g. a header +from another library or from a common set of includes). ##### Example // foo.cpp: #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 // A file in the same project located via a search path, use the <> form + #include // A file that is not locally relative, included from another library: use the <> form + #include "foo.h" // A file located relative to foo.cpp: use the "" form + #include "foo_utils/utils.h" // A file located relative to foo.cpp: use the "" form + #include // A file located via the header search path: use the <> form ##### Note -Failing to follow this results in difficult to diagnose errors due to picking up the wrong file by +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 might 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 +search algorithm might search for a file existing at a locally relative path first, then using this form to refer +to a file that is not locally relative could mean that if a file by that name ever comes into existence at the +locally 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 ` +Library creators should put their headers in a folder and have clients include those files using +angle brackets: `#include `. ##### Enforcement -A test should identify headers referenced via `""` could be referenced with `<>`. +A tool could identify headers referenced via `""` that could have been referenced with `<>`. ### SF.20: Use `namespace`s to express logical structure