Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

add F.12: Describe when to use the different forms of #include #1456

Closed
wants to merge 7 commits into from
Closed

add F.12: Describe when to use the different forms of #include #1456

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
c3d4138
add SF.12
Jun 25, 2019
7b280fb
add incscope to isocpp.dic to get the CI build to pass
ChrisGuzak Jun 27, 2019
cd2891c
expand INCLUDES, update dictionary for the ci build to pass
ChrisGuzak Jun 27, 2019
15f404c
pr feedback
ChrisGuzak Jun 28, 2019
edaff81
in the same directory
ChrisGuzak Jun 28, 2019
33fb721
update based on feedback
ChrisGuzak Nov 22, 2019
8b1871f
Merge branch 'master' of https://github.com/isocpp/CppCoreGuidelines
ChrisGuzak Feb 22, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
25 changes: 25 additions & 0 deletions CppCoreGuidelines.md
View file
Open in desktop
Expand Up @@ -18743,6 +18743,7 @@ Source file rule summary:
* [SF.9: Avoid cyclic dependencies among source files](#Rs-cycles)
* [SF.10: Avoid dependencies on implicitly `#include`d names](#Rs-implicit)
* [SF.11: Header files should be self-contained](#Rs-contained)
* [SF.12: Use the quoted or angle bracket form of `#include` to distinguish standard headers from others](#Rs-incscope)

* [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)
Expand Down Expand Up @@ -19181,6 +19182,30 @@ A header should include all its dependencies. Be careful about using relative pa

A test should verify that the header file itself compiles or that a cpp file which only includes the header file compiles.

### <a name="Rs-incscope"></a>SF.12: Use the quoted or angle bracket form of `#include` to distinguish standard headers from others

##### Reason

To understand dependencies it is important to know where included files come from. Given the different search algorithms,
the angle form (`<>`) identifies standard headers, the quoted (`""`) everything else.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This contradicts the note I mentioned:

in general programmers should use the < > form for headers provided with the implementation, and the " " form for sources outside the control of the implementation.

That strongly suggests that angle brackets should be used for non-standard headers "provided with the implementation" such as Windows.h and unistd.h, or system libraries like zlib.h or Python.h. Limiting it to just standard headers is too restrictive, and ignores the "in between" cases that are not standard headers but also not one of the project's own source files.

I have no idea how Windows does things, but on many POSIX systems it doesn't make sense to do #include "X11/Xlib.h" with quotes but #include <stdio.h> with angle brackets, when both are likely to be found in /usr/include.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is still too restrictive. It's often appropriate to use <> to include headers from within the same project.


##### Example

#include <string> // From the standard library, use the <> form
#include "helpers.h" // A project specific file, use "" form

##### Note

This is specified [here](http://eel.is/c++draft/cpp.include) in the standard.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems like http://eel.is/c++draft/cpp.include#8 would be a slight improvement on the link


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.
ChrisGuzak marked this conversation as resolved.
Show resolved Hide resolved

Library creators should put their headers in a folder and have clients include those files using the relative path `#include "some_library/common.h"`

##### Enforcement

A test should verify that the headers referenced via `<>` are from the standard library and those using `""` are not.

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

##### Reason
Expand Down
1 change: 1 addition & 0 deletions scripts/hunspell/isocpp.dic
View file
Open in desktop
Expand Up @@ -244,6 +244,7 @@ incomplet
incorrekt
increment1
Incrementable
incscope
indices
ing
init
Expand Down