isocpp / isocpp/CppCoreGuidelines

SF.12 is ambiguous when a library uses a unique include subfolder

Open
#1,980 7 comments 0 reactions 1 assignee View on GitHub

@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:

  1. Amend the general rule to exclude the case of a library-specific include subfolder/prefix.
  2. 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.