30

On the question C/C++ include file order/best practices, the best answer recommends to include the related header first.

Same for Google and Mozilla style guides.

However, in both cases, I couldn't find a good reason why you would do this.

Google and Mozilla coding rules look best to me, because they enforce you to include the most "standard" headers first.

This way, I think you are less likely to mess up the included files (for examples by undefining some macros used in the other headers etc.) so that looks like the best way to go for me.

But following that rationale, why would you include the related header first? Since any syntax error in it might mess all the following headers?

I would think including the related header last would be best instead.

Konrad Rudolph
  • 530,221
  • 131
  • 937
  • 1,214
Arnaud
  • 536
  • 5
  • 13
  • @user463035818 - Updated my answer accordingly. Google prohibits forward declarations IIRC, so that's a bit of rationale they won't post about. – StoryTeller - Unslander Monica Oct 09 '18 at 08:58
  • The use of the term "related" is quite vague. All includes should be "related" otherwise why have them? Please correct this, possibly using the original term from the question you cited, "corresponding". – Lightness Races in Orbit Oct 09 '18 at 10:11
  • 1
    @StoryTeller They don’t *forbid* forward declarations, and this would severely limit the set of correct, useful code they could write (any kind of circularity requires forward declarations unless you erase all types). They limit the use to those cases where it’s necessary. – Konrad Rudolph Oct 09 '18 at 11:25
  • @KonradRudolph - Re-reading it now, it does seem less draconian than I seemed to remember. I still don't feel it's worth mentioning in a style guide at all, to be frank. But it's their prerogative. – StoryTeller - Unslander Monica Oct 09 '18 at 11:33
  • @StoryTeller Yes, agreed. The Google C++ style guide in general is still at best a waste of time, and at worst very bad advice (though it has improved tremendously from past versions). Unfortunately it’s so prominent that it feels authoritative to many people. – Konrad Rudolph Oct 09 '18 at 11:35

2 Answers2

42

It's to make sure your clients don't hate you when they include your library header.

If the header is brittle and subject to break on wrong inclusion order, it may appear to work in your environment when it isn't first - since you include the headers you need - but fail to compile for client code. Because it may not at all be obvious what other headers need to be pulled in for it to work.

Including first the header which corresponds to the current implementation file goes toward checking that the header is self-contained. Self-containment goes beyond just including the necessary headers. It also entails adding the required forward declarations for types you use in your API. Naturally your header will compile if you include the header for the type before it, but you may not wish to pull it in since you only depend on the type name in your API.

Some style guides prohibit forward declarations, so those may not be part of the rationale they pose.

StoryTeller - Unslander Monica
  • 165,132
  • 21
  • 377
  • 458
15

Including the header related to the cpp file first ensures that the header is self contained and doesn't require other includes to compile

Alan Birtles
  • 32,622
  • 4
  • 31
  • 60
  • 5
    Why the downvote? May be a bit short, but is correct. – Rene Oct 09 '18 at 08:47
  • 1
    "ensures that the header is self contained" - ensuring this is not possible in general. Situation when [header file may be not self contained but works on current platform because on that platform required header gets included indirectly](https://wandbox.org/permlink/iJCZrHEsz0PaS95b) is quite typical and yet difficult to detect until you actually get an error. Including project headers prior to library headers may indeed help to detect whether related header is not self contained, but may not ensure it. – user7860670 Oct 09 '18 at 08:59
  • 2
    @VTT - Ensure? No. Provide *some* checks which are better than none? Yes. – StoryTeller - Unslander Monica Oct 09 '18 at 09:00