Remove the NL.27 suggestion for use of .h as the filename extension for headers

[eyalroz]

_{(For context, see below)}

Regarding: "NL.27: Use a .cpp suffix for code files and .h for interface files (https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rl-file-suffix)

The core guidelines should not suggest using .h as the file extension for header files, by default in new C++ projects. This is because:

1. Using .h clashes with the .h file extension for C language headers.
2. The rationale for using .h is that, supposedly, C++ headers are shared between C++ and C; but - this is in fact uncommon, and arguably very rare for new C++ projects.
3. The use of .h, while popular, is neither a universal nor a near-universal convention.
4. (I claim that) We have an interest in strengthening the distinction between C and C++, against the continuing custom in media coverage and policy recommendations to talk about "C/C++" as though the languages should be treated similarly.

Possible courses of action:

1. Remove the recommendation from NL.27, i.e. make it "Use a .cpp suffix for source code files" (or even remove NL.27 entirely, not making any recommendation about file extensions)
2. Limit the suggestion in NL.27 to projects which do not involve cross-language C-and-C++ work, and recommend .hpp for that case.
3. Split the recommendation in NL.27 between the case of shared C-and-C++ headers, where .h would be suggested, and C++-only headers or C++-only projects, in which .hpp is suggested. In this case, the title would be "use .hpp or .h for header files", and the body would explain when each is recommended.

... and recall that when we don't suggest anything, the general rule for the NL section still applies: Consistency with existing stylistic/naming choices in a project is important and should be maintained.

See also the discussion of this matter on StackOverflow, where a much larger group of users/developers have opined on this matter over the years, and the vast majority believes .hpp should be used.

---

Context:

This suggestion used to be a rule, SF.1. Issue #1965, suggesting a change, was opened and discussed in 2022. Most discussants believed that .hpp is a better choice for header file name extensions (and implicitly, that it's what should be suggested). A single discussant supported the recommendation of .h because of the cross-language use of header files, and under the premise of "the vast majority of [C++] header files out there [being] compatible with C."

An "editor's call" was made to move the recommendation to the NL section, as header file naming is a "if you have no better convention already" kind of thing. But no call was made regarding the actual validity or benefit in recommending the use of .h extensions. @cubbimew said that "there was no consensus to choose hpp over other header naming conventions." - which is technically true, but the majority was against .h and in favor of .hpp, with no case being made for .h in non-cross-language scenarios.

[Spongman]

Agreed. There should be a different extension for files that cannot be used in C.

[LegalizeAdulthood]

Meh, this feels really subjective and specific to personal tastes and habits and doesn't feel like something that belongs in the guidelines at all.

[eyalroz]

Meh, this feels really subjective and specific to personal tastes and habits and doesn't feel like something that belongs in the guidelines at all.

For those who believe that - the course of action should be (1.) removing the recommendation altogether.

And for those who do find it important to make a recommendation - the course of action should be (2.) or (3.)

[carlosgalvezp]

I agree with removing the recommendation altogether and letting people choose whatever extension they like.

The main problem I see is tying filename to file contents. What if today, the file is C/C++ compatible, thus called .h, and tomorrow, we remove the C part and it becomes C++-only? Should we rename the heather and update all the include locations in thousand of files? It's easy to do in practice, but it just creates unnecessary churn.

[AdreKiseque]

The fact that .h is used for C++ headers baffles me. C and C++ are not the same language, the file extensions should reflect that.

[carlosgalvezp]

C and C++ are not the same language

Agreed. However, where exactly do you draw the line between C and C++? What language feature decides if your code is no longer C and becomes C++?

I suppose we need a clear, standardized definition to be able to separate both languages (and thus choose the right file extension)?

[AdreKiseque]

I don't work too much in C++, so my perspective is rather limited, but the way I see it is this: C++ is a(n imperfect) superset of C; it's designed to be backwards compatible, and in most cases it is. Sometimes C++ code may, to some degree, work in C, but it isn't a rule. When you give a file a C++ extension, it is a declaration of its limitations, a message that the code may require the features provided by C++ to fully function. Conversely, when a file is given a plain C extension, it is a promise that the code does not require the extensions of C++, and is written entirely in compliance with the original language. All of which is to say, a file should only have a plain C extension if it is completely written in C—if it has any more, it no longer fits into the set, and shouldn't be labeled as though it does.

But this is just my uninformed take, I know for a fact there are edge cases I haven't considered. Hopefully, something elegant can be put together to answer this question.

[eyalroz]

Agreed. However, where exactly do you draw the line between C and C++? What language feature decides if your code is no longer C and becomes C++?

That's a decent question, but - let me bravely sidestep it in the context of this issue: 😛

The line is certainly at some distance from your starting point. That is, when you start writing your (typical) C++ header, you are on the C++-and-not-C side of that line. And then, it is for you as the author to consciously decide that you've crossed that line, in which case you might change the extension from .hpp (or .hxx or .hh or whatever), to .h. The current recommendation is for people to always be past that line, and that's not the right thing to suggest.

[carlosgalvezp]

I like the perspective of "it's not about the content of the file, it's about the promise the user makes".

• .cpp / .hpp promises that the file can be processed by a C++ tool.
• .c /.h promises that it the file can be processed by a C tool.

And since C++ is backwards compatible with C, any .c or .h file can be processed by a C++ tool, but not the other way around.

[jwakely]

The "promises that a file is valid C" position presupposes that a .h extension is exclusive to C code. But it's not, there are decades of established practice using .h for pure C++ files, for files that work in both C and C++, and for files that do not work in C++.

It's too late to close that door.

[jwakely]

And since C++ is backwards compatible with C,

It isn't.

any .c or .h file can be processed by a C++ tool

No, because C files can contain variable length arrays, or the restrict keyword, or static array bounds, or compound literals, or _Generic, or ...

[carlosgalvezp]

there are decades of established practice

But the point of the C++ Core Guidelines is precisely to use best practices, typically modern practices, instead of using "decades of established practice" (for example, replace decades of established C arrays with std::arrays). Why would file extension be an exception?

[jwakely]

You can say that best practice is to not use .h for C++, but you can't say that any .h header promises that it can be consumed by any C tool. It's only a promise for code known to follow the C++ Core Guidelines, which is not all code, so it's not a promise.

[eyalroz]

@jwakely:

you can't say that any .h header promises that it can be consumed by any C tool.

That's true, but:

You can say that best practice is to not use .h for C++ ... It's only a promise for code known to follow the C++ Core Guidelines, which is not all code, so it's not a promise.

you're forgetting the other side: .hpp is a promise to be C++ rather than C.

And even by your earlier - that .h doesn't guarantee much - we should still not recommend it.