isocpp / isocpp/CppCoreGuidelines
SF.12 is ambiguous when a library uses a unique include subfolder
@cubbimew is already working on this.
Since Oct 13, 2022.
- Dominant language
- CSS
- Stars
- 45.3k
- Forks
- 5.6k
- PR merge metrics
- No merged PRs in 30d
Description
(See also this SO question.)
Rule SF.12 says we should
use the quoted form for including files that exist at a relative path ...
because:
This encourages being clear about the locality of the file...
and
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).
but - what about the case where locality is clear, because the library uses a unique include subfolder? e.g. #include <my_lib/some_file.hpp>? In fact, in this case, another, more specific part of SF.12 seems to apply:
Library creators should put their headers in a folder and have clients include those files using the relative path
#include <some_library/common.h>
as a library's include file is also a "client" of the library's (other) include files.
It is also worth mentioning that the Boost libraries seem to prefer angle-brackets for files known to be accessible via relative paths.
So, I suggest one of two things:
- Amend the general rule to exclude the case of a library-specific include subfolder/prefix.
- Clarify that, within a library's include files, one should prefer quoted include paths
I'm a bit partial to (1.) - it's my personal style so far - but don't have a strong opinion.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.