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.

[jwakely]

I'm not forgetting it, I'm commenting on the .h part of the statements above.

[carlosgalvezp]

I agree with .h not promising much, I take my previous statement back :)

[AdreKiseque]

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++.

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.

Of course. No one is saying to go through all legacy code in the world and update the file extensions based on new conventions, or that this "promise" will apply retroactively. We're here because the way things currently are is misleading, counterproductive, and broken. We're here because we want things to be better moving forward, and establishing a "promise" to keep as a guideline when naming files is a good way to move towards that.

Just because things have been done one way for a long time doesn't mean we can't improve on it, and I will remind you that .h for C++ headers is far from a universal and consistent convention.
We can't change the past, but we can, at the least, stop actively encouraging the inefficient way things have been done in the past.

It's too late to close that door.

It's never too late to start making things better for the future.

[AdreKiseque]

We're here because the way things currently are is misleading, counterproductive, and broken. We're here because we want things to be better moving forward, and establishing a "promise" to keep as a guideline when naming files is a good way to move towards that.

To expand on this, .h does not currently promise a file is pure C, and it probably never will. But maybe it should, and just because things will never be perfect doesn't we shouldn't work towards making them better.

[jwakely]

To expand on this, .h does not currently promise a file is pure C, and it probably never will.

That's the point I was making, that's all.

But maybe it should, and just because things will never be perfect doesn't we shouldn't work towards making them better.

I wasn't suggesting otherwise.

[dorrellmw]

I don't write enough C++ to feel justified directly expressing agreement or disagreement with this issue, but I have a couple of thoughts which might not have been considered. I might even be playing devil's advocate.

First, the ambiguity of .h encourages doubt, and that might or might not be a bad thing. It requires people (and tools) to actually look at the contents to determine what it is. I leave it up to others to decide whether people should be expected to read header files before including them.

Second, perhaps .h files should be recognized as "C preprocessor files" instead of "C header files" or "C/C++ header files". After all, headers intended for C++ projects do not necessarily contain valid C++ code, nor do headers intended for C projects necessarily contain valid C code. This complicates any tool that tries to interpret a header file, except perhaps for code editors and syntax highlighters (where parsing failures are not critical). I'll include two contrived examples below.

Third, perhaps it would be constructive to create a long list of software which cares about .h versus .hpp. Then people can evaluate any technical consequences of recommending one or the other.

Examples:
I've seen instances like this first example in major open source projects.

/* funcsig.h */

#define UNARYFUNC(funcname, argtype) argtype funcname(argtype n)

/* header.h */

#include "funcsig.h"
UNARYFUNC(square,float)
{
	return n * n;
}

/* code.c */

#include "header.h"
int main(int argc, char *argv[])
{
	return (square(3) > 6);
}

I can't recall seeing a particular instance like this second example, but it illustrates that even if a tool can follow #include directives, the code may still be invalid if the tool starts in the header file.

/* badheader.h */

UNARYFUNC(square,float)
{
	return n * n;
}

/* badcode.c */

#define UNARYFUNC(funcname, argtype) argtype funcname(argtype n)
#include "badheader.h"
int main(int argc, char *argv[])
{
	return (square(3) > 6);
}

The only safe way to parse a header file is to build up the whole context starting from something that isn't a header file. But then again, maybe bad code shouldn't be a factor in recommended practice.

I don't know -- I'm just dropping in some ideas to hopefully inspire some insightful discussion amongst people smarter than me.

[eyalroz]

Second, perhaps .h files should be recognized as "C preprocessor files" instead of "C header files" or "C/C++ header files".

Remember we are discussing only the C++ community's core guidelines document - nobody here has any presumption to set any policies or conventions for the C language.

[dorrellmw]

Second, perhaps .h files should be recognized as "C preprocessor files" instead of "C header files" or "C/C++ header files".

Remember we are discussing only the C++ community's core guidelines document - nobody here has any presumption to set any policies or conventions for the C language.

Yes, of course! I fully understand that, and I'm sorry for being unclear. The concept was that if we dispel the notion that .h has anything to do with C, then there's no reason that C++ shouldn't recommend using .h as well.

If I'm wrong, and C++ does not actually use the C preprocessor, then the whole idea should be completely disregarded.

As for my actual personal opinion, I think I'm leaning toward the idea that headers shouldn't have any extension at all. I'm very interested in hearing more people justifying their perspectives, though, because I don't hold my opinion strongly.

[AdreKiseque]

As for my actual personal opinion, I think I'm leaning toward the idea that headers shouldn't have any extension at all. I'm very interested in hearing more people justifying their perspectives, though, because I don't hold my opinion strongly.

I have pretty strong opinions on that idea but I'll just raise you this: What would stripping header files, which are essentially just a particular type of source file for a programming language, of their extensions accomplish besides making things more ambiguous?

[dorrellmw]

What would stripping header files, which are essentially just a particular type of source file for a programming language, of their extensions accomplish besides making things more ambiguous?

Off the top of my head, I think most file extensions control how software interacts with a file, don't they? At this moment, I can't think of many examples where the file extension exists purely to be informative for humans. Information for humans generally goes before the dot.

If there's no need to tell software anything about the file, then there's no need for an extension.

(But I'm not 100% sold on that -- it won't take much to convince me otherwise.)

[AdreKiseque]

Off the top of my head, I think most file extensions control how software interacts with a file, don't they?

I disagree, file extensions are just as much for the human working with a file as they are for the computer. Just as a .png extension tells the computer to open a file in an image processor, it tells the person looking through the file that it's an image file.

At this moment, I can't think of many examples where the file extension exists purely to be informative for humans.

Programming source files are possibly one of the best instances of this, actually. They're all just text files in the end, after all—there's nothing different about the way data is stored in a .c or .sh or .rs or .ps1 file; they all open in a text editor all the same. And, yeah, these days there are tools that might look for these extensions and use them to gather data, but oftentimes you're telling your compiler or interpreter or whatever which file to open explicitly, and it doesn't care about the extension, it just cares that it exists. But for the human looking through a project directory with lots of source files in it, those extensions are very important for determining what kind of file it is without needing to open each one up and take a look.

[carlosgalvezp]

Information for humans generally goes before the dot.

Have you ever found yourself enabling the "Show file extension" option on Windows? :)