Skip to content

Commit 3de0a91

Browse files
committed
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?
1 parent c6dbec6 commit 3de0a91

File tree

1 file changed

+15
-15
lines changed

1 file changed

+15
-15
lines changed

Diff for: CppCoreGuidelines.md

+15-15
Original file line numberDiff line numberDiff line change
@@ -19298,37 +19298,37 @@ the two forms of `#include` selected using the angle (`<>`) or quoted (`""`) syn
1929819298
advantage of this and use different search algorithms and methods for specifying the include path.
1929919299

1930019300
Nevertheless, the guidance is to use the quoted form for including files that exist at a relative path
19301-
to the file containing the `#include` statement (from within the same component or project) and to use
19301+
to the file containing the `#include` statement and to use
1930219302
the angle bracket form everywhere else, where possible. This encourages being clear about the locality
1930319303
of the file relative to files that include it, or scenarios where the different search algorithm is
19304-
required. It makes it easy to understand at a glance whether a header is being included from a local
19305-
relative file versus a standard library header or a header from the alternate search path (e.g. a header
19306-
from another library or a common set of includes).
19304+
required. It makes it easy to understand at a glance whether a header is being included from a locally
19305+
relative file, versus a standard library header or a header from the header search path (e.g. a header
19306+
from another library or from a common set of includes).
1930719307

1930819308
##### Example
1930919309

1931019310
// foo.cpp:
1931119311
#include <string> // From the standard library, requires the <> form
19312-
#include <some_library/common.h> // A file that is not locally relative, included from another library; use the <> form
19313-
#include "foo.h" // A file locally relative to foo.cpp in the same project, use the "" form
19314-
#include "foo_utils/utils.h" // A file locally relative to foo.cpp in the same project, use the "" form
19315-
#include <component_b/bar.h> // A file in the same project located via a search path, use the <> form
19312+
#include <some_library/common.h> // A file that is not locally relative, included from another library: use the <> form
19313+
#include "foo.h" // A file located relative to foo.cpp: use the "" form
19314+
#include "foo_utils/utils.h" // A file located relative to foo.cpp: use the "" form
19315+
#include <component_b/bar.h> // A file located via the header search path: use the <> form
1931619316

1931719317
##### Note
1931819318

19319-
Failing to follow this results in difficult to diagnose errors due to picking up the wrong file by
19319+
Failing to follow this results in difficult-to-diagnose errors due to picking up the wrong file by
1932019320
incorrectly specifying the scope when it is included. For example, in a typical case where the `#include ""`
19321-
search algorithm may search for a file existing at a local relative path first, then using this form to refer
19322-
to a file that is not locally relative could mean that if a file ever comes into existence at the
19323-
local relative path (e.g. the including file is moved to a new location), it will now be found ahead
19321+
search algorithm may search for a file existing at a locally relative path first, then using this form to refer
19322+
to a file that is not locally relative could mean that if a file by that name ever comes into existence at the
19323+
locally relative path (e.g. the including file is moved to a new location), it will now be found ahead
1932419324
of the previous include file and the set of includes will have been changed in an unexpected way.
1932519325

19326-
Library creators should put their headers in a folder and have clients include those files using the
19327-
relative path `#include <some_library/common.h>`
19326+
Library creators should put their headers in a folder and have clients include those files using
19327+
angle brackets: `#include <some_library/common.h>`.
1932819328

1932919329
##### Enforcement
1933019330

19331-
A test should identify headers referenced via `""` could be referenced with `<>`.
19331+
A tool could identify headers referenced via `""` that could have been referenced with `<>`.
1933219332

1933319333
### <a name="Rs-namespace"></a>SF.20: Use `namespace`s to express logical structure
1933419334

0 commit comments

Comments
 (0)