header, cpp file and namespace structure / library organisation

[adam-ce]

This partly overlaps with #497, but imo it's broader, so opening another issue.

I wonder whether it would make sense to make guidelines for structuring the headers and cpp files of libraries. For instance currently

• the stl has toplevel headers (<vector>), but a std:: namespace
• opencv uses <opencv2/core/mat.hpp> and <opencv2/core.hpp>, and a cv:: namespace
• qt uses toplevel <QString> but alternatively also <QtCore/QString>, and the Q prefix (the prefix afaik for historical reasons)

Imo there should be guidelines for:

1. Where to put the header files (top directory (stl) vs. library dir (opencv)? That's mainly a packaging and project setup thing, but why not provide guidelines?
2. Should there be a general namespace for the company, or the library? Should it be long and descriptive or short (2-3 letters)?
3. How to organise functionality?
   3.1 Should namespace names follow the directory structure?
   3.2 When should i put a group of classes into a subdirectory?
   3.3 When should i use namespaces, separate classes or subclasses?
4. Build systems, specifying that there should be no conflicts when building two .cpp files with the same name but a different path (out of scope?)

Examples for 3.:

1. Say, i have an abstract base class and many derived classes. Should the derived classes go into a subdirectory? What about the base class? What about naming? E.g. for shapes, should it be "abstract_shape, circle_shape, triangle_shape, etc.", "shape, circle, triangle", or rather "shape::base, shape::circle, shape::triangle" etc with a namespace and directory shape? There are implications for instance for code completion (when typing I don't remember which shapes exist and which not, I'd like to have suggestions).
2. Say i have building blocks, each with certain repetitive classes "shape::object, shape::settings, shape::factory etc.". Should there be a namespace shape as in the example, separate classes "shape, shape_settings, shape_factory etc.", or subclasses of shape "shape, shape::settings, shape::factory etc."?

[jwakely]

There's no one-size-fits-all guideline. A single person project with a few files and classes can use any style. A large team with hundreds of files should use whatever works best for the team (and for some projects it would make sense to structure the code according to ownership of modules within the team, for other projects that wouldn't work).

This is dealt with in detail in the book Large Scale C++ Software Design, see http://www.cs.unc.edu/~stotts/COMP204/lakos/ for an overview of the physical design rules.

[cubbimew]

This is essentially our old second To-do proto-rule , suggested to be abandoned in #811 (comment)

[adam-ce]

yes, physical design. I hope it'll be covered when modules are there :)

what about part 4. though?

[hsutter]

Editors call: We'll postpone this until we have modules broadly available. For now there are too many existing practices, none obviously universally best. We don't want to say anything about build systems.