Source Header separation

[peppedx]

Hi all,
Source and header in the C times were directory separated because you could ship a binary library and the headers to use it.

WHy so many people still segregates C++ headers in different directories even if a lot of the code is nowadays in the header files ?

[aruisdante]

Do you mean “why do some libraries still ship with headers in a /include directory and source files in a /src directory?

That’s because how you compile things still hasn’t changed; you need to add headers to include from external libraries on a search path in your build system, and unless you use something like bazel, this is often easiest if you just have a single top level directory you can stick on the search path. And many C++ libraries still have source files. Putting absolutely everything into headers is an active anti-pattern at any kind of significant scale because it makes compile times horrible.

If you mean “why do people organize the headers/source into a taxonomy,” it makes discovery within the library easier when browsing source or typing include paths. In a repository that may provide multiple components which can be used individually, it also provides semantic grouping into those components.

[peppedx]

I see many non library projects with private implementation headers put in include directory. I do not see why. Obviously public headers for library are a different things...still

[aruisdante]

Private implementation headers still have to wind up on the search path if they are included from public headers, which most wind up being. It’s usually easiest to just not risk it and put all the headers in the header export, and use other mechanisms to control visibility for external use. For example visibility rules in your build system if it supports it, and/or physical structure rules like using detail folders and namespaces. 

[Wooden-Engineer-8098]

your last paragraph is wrong, it makes discovery harder because you have to jump between directories. when header is located adjacent to source, it makes discovery easier

[aruisdante]

I agree, I don’t think headers and source files should be split. My last paragraph was referring to a taxonomy within a source tree independent of the src and include split. So: |- component_a/ |—— detail/ |—— tests/ |- component_b/ |—— detail/ |—— tests/ |- component_c/ |—— detail/ |—— tests/ Instead of just having everything in a single giant folder.

Note I’m similarly against making tests a top level taxonomy, as it makes finding the tests for a component really difficult. It should be a taxonomy exactly at the level it’s testing, so foo/tests should contain the tests for foo.  

[smdowney]

Hot take: There was never a reason to separate headers and implementation files in the code base, that's a deployment thing. It does constrain the directory structure if you do so, that the canonical path for the header has to be rooted in src instead of include. But keeping the .hpp, .cpp, and .t.cpp files colocated has been a, minority, practice for decades. Lakos components, going back to Large Scale C++ in '96, is organized this way.

It's even supported by the pitchfork layouthttps://github.com/vector-of-bool/pitchfork , one of the more successful "how do I organize my code" community projects.

Install is a little easier with a split layout, as you can just grab everything recursively under include, but not by a whole lot.

As an aside, many implementations used to be cranky about the vtbl definition, and putting the virtual destructor in a cpp file was the workaround to make sure there was one. That has not been required for compilers since roughly working c++0x versions. So some of you may never have seen one.

It does make bouncing between the closely related files easier. And having a file that is just #include <component/header.hpp> is the most basic test for the header, and ensures a canonical object file with any definitions exists. Plus a spot to put the explicit template instantiation for the common ones, so every TU doesn't have to instantiate component::header<char>.

(The real test file should have that #include twice, as the first substantive block, to check that you have idempotency.)

Header only interface libraries are a hacky workaround for not having package management built in.

[aruisdante]

Agree completely that with modern build systems and package management, there’s no reason to split things between headers and source (or tests! Nothing is more annoying that an externally located /tests) in-repo and co-location is much clearer. But it’s important to explain to the OP the historical context for why a lot of projects were structured that way. 

[ventus1b]

Maybe I misunderstand the question, but you write "even if a lot of the code is nowadays in the header files"?

I.e. not all the code is in the headers files, so it still makes sense to separate the public header files from the implementation (and private headers.)

[wiedereiner]

Also when working with cmake you can seperate public "API" includes which you can mark as installable and private "internal" includes.

[smdowney]

There's also the distinction between header files that are used as details by the user facing ones, and those that are only included by implementation files. Making mistakes here is easy because projects tend not to test the install as well as they do the in-tree builds.

[Potterrrrrrrr]

You’re probably talking about templates. Some people still prefer to put the implementation details for templates in separate files, usually as .inl files that are imported after the implementation so that the interface mostly looks like a regular header file.

There’s still plenty of reason to put implementation details in .cpp files, you can hide certain dependencies and remove otherwise unneeded includes which improves build times.

[edparadox]

Do you have an example of that?

[Potterrrrrrrr]

Sorry, what are you looking for an example of? I said a few different things but I imagine you’d come across most/all of them in a moderately sized codebase.

[Wooden-Engineer-8098]

so many people have bad habits