In my time with C/C++ I have encountered different ways to handle the file path for the #include directive when including your .h file in your .cpp/.c file. The Google style guide alludes to using part of the file path in your #include. That being said, I currently work on a project (albeit a small one) where a nicely laid out Makefile (for G++) and structure was laid out for me when I "inherited" the code. Namely, there is a directory named /project_name and inside is the Makefile and several sub-directories. For example, /project_name/inc holds the .h files and /project_name/src holds the .cpp files. The Makefile is set to look into each sub-directory to compile the source code.
My question is, given the directory structure and the Makefile, what is the "preferred" method for #include. The two alternatives I am successful with using are listed below.
include "mycode.h" // no knowledge of path, assumes structure that I described
include "../../project_name/inc/mycode.h" // seems a bit convoluted, but shows the file structure better
Are there any other options that I'm missing?
Use neither. Rather, put all your public headers in some hierarchy with a single root. For instance if your project is foo, put all your public headers in, say, include/foo, but don't hesitate to group your headers per component:
include/foo/io/printer.hh
include/foo/io/reader.hh
include/foo/job/job.hh
include/foo/job/scheduler.hh
Then if your code use only <foo/io/printer.hh> and so forth, which requires that you pass the proper -I $(top_srcdir)/include flags during construction of your project. This set-up simplifies things if you have to install your headers, as your code and users' code will use the headers exactly the same way.
If in addition you have private headers, use the same structure, but in another hierarchy, for instance:
src/io/parser.hh
You may, or may not, decide to use src/foo. The advantage of not using src/foo is that it is easier to see what are public and private headers.
But never use relative paths.
The first option appears as the less constraining.
If tomorrow the structure of the project directory changes, would you rather modify one makefile or change every single custom #include to take the change into account ?
Using the second option will make changes to the directory structure take more time, and the time needed to adapt everything will scale with the project size (whereas with the makefile change, it's constant).
This is a subjective answer; if both work then both are correct, however I prefer to have no knowledge of the source tree within the source code, only in the project settings/Makefile, so for me the first option is best:
#include "mycode.h"
As trojanfoe says, it is very subjective but still I would go with this style below.
#include "mycode.h"
If at all there is a need to restructure folders having.cpp/.h files, then the below style becomes fragile and bound to fail. You will be forced to change the .cpp files to provide the correct relative path.
#include "../../project_name/inc/mycode.h" //
it seems that include code structure in #include(i.e. option2) will make code less portable.
i recently met problem when bring a component(that build with jam) to cocoapod to be consumed by IOS. the main problem is that in the code there are following code
`#include <impl/xxxxx.h>`
when bring into cocoapods, it will not compiled because the path of "impl" is not recoginized and i did not find a setting for that.(i am be wrong, just share what i got now). change to
`#include "impl/xxxx.h" `
will make this pod compiled succ, but still not be used be client. sicne client code have no idea about the "impl" structure.(if the public interface has no this strucutre include, it will work. but it is not my case)
i end up with removing all this source structure include which becomes to use option 1..
so my point is that.
1) for public header, avoid include source structure.
2) for private header/code, use "private/source/structure/xxxx.h" to easy compile setting.
please share with me if anything.
Related
I am trying to write my first (very) small, for now only self-use, library. In the process I came across questions regarding how I should separate my headers/source code/object files in a logical way.
To be more specific, I'm writing a small templated container class, so for one I have to include the implementation of this class inside its header.
I have a directory structure like this:
include/ - "public" .hh header files included by extern projects
src/ - .cc files for implementation (+ "private" .hh header files?)
lib/ - .o compiled library files linked by extern projects
I am already not sure if this makes sense.. in my case I also wrote some helper-classes used by my templated container class, one of which is something like an iterator. So I have the following files:
container.hh
container.cc
container_helper.hh
container_helper.cc
container_iterator.cc
container_iterator.hh
While I want to have access to their functions in external projects (e.g. incrementing the iterator), it makes no sense to me that a project would specifically
#include "container_iterator.hh"
Now, since I want projects to be able to use the container class, I put "container.hh" and "container.cc" (since it must be included in "container.hh" because of the template) into the "include/" directory, which is then included by other projects.
Now my confusion arises.. the container class needs access to the helper classes, but I don't want other projects to only include the helper classes, so it seems wrong to place also the helper classes into "include/" directory. Instead, I would place them in "src/".
But if I do this, then to include these in "include/container.cc" I have to use relative filepath
#include "../src/container_iterator.hh"
But now if I "distribute" my library to an external project, i.e. I only make the "include/" directory visible to the compiler, it will not compile (?), since "../src/container_iterator.hh" does not exist.
Or do I compile the container class and put it as library into "lib/", which is then linked by other projects? But even then do I not still need to include the header "container.hh", to be able to find the function declarations, which leads to the same problem?
Basically I'm lost here.. how does the standard do this? E.g. I can
#include <vector>
, but I don't know of any header to only include std::vector::iterator, which would make no sense to do so.
At some point in my expanation I must be talking nonsense but I cannot find where. I think I understand what a header and a library is/should be, but when it comes to how to design and/or "distribute" them for an actual project, I am stuck. I keep coming across problems like this even when I started learning C++ (or any language for that matter), no course / no book ever seems to explain how to implement all these concepts, only how to use them when they already exist..
Edit
To clarify my confusion (?) more.. (this got a bit too long for a comment) I did read before to put implementation of templated classes into the header, which is why I realized I need to at least put the "container.cc" into the include/ dir. While I don't particularly like this, at least it should be clear to an external user to not include ".cc" files.
Should I take this also as meaning that it never makes sense to compile templated classes into a library, since all of it will be always included?
(So templated code is always open-source? ..that sounds wrong?)
And in this case I still wonder how STL does it, does vector declare & define its iterator in its own header? Or is there a separate header for vector::iterator I could include, it just would make no sense to do so?
Hopefully I explained my intent clearly, please comment if not.
Thanks for any help!
In my experience, the most common method to handle your problems is to have headers with the template declarations and documentation (your .hh files), which also include .inc or .tcc (your preference) files with the template definitions. I also suggest keeping all files that may be included by external projects in the same folder, but if you want to keep things clean, put your .inc/.tcc files in a folder within include called detail (or bits if you like GNU style).
Putting stuff in a detail folder,
and using a weird extension should deter users enough.
To answer your other questions:
Due to the nature of C++ templates,
either the entire source of the parts of a template you use
must be present in the translation unit (ie. #include'd),
or you can use explicit instantiation
for a finite number of arguments
(this is not generally useful for a container, though).
So, for most purposes, you have to distribute a template's source, though,
of course, (as mentioned in the comments) "open source" is about licence,
not source visibility.
As for the standard libraries, lets use <vector> as an example.
The GNU C++ Library has a vector file that (among other things) includes
bits/stl_vector.h which has the declarations & documentation,
and includes a bits/vector.tcc that has the definitions.
LLVM's libc++ just has one giant file,
but puts the declarations at the top (without documentation!)
and all the definitions at the bottom.
As a final note, there are lots of open source C++ libraries that you can take a look at for inspiration in the future!
I'm building a little language that will compile to C or C++, I haven't decided yet, however I have come across a dilemma concerning the #include keyword.
My language will come with a standard library that will be incorporated into the language, and be accessible much like that of C or C++ with the standard includes such as #include <string>.
My compiler can automatically tell the difference between user includes and standard library includes, but my issue lies in how the GCC compiler uses the -I flag.
Let's take Java as an example. One of the default packages (folder) is called java.util. If I try to make my own folder called java.util inside my project, I get the error:
The package java.util conflicts with a package accessible from another module: java.base
Meaning it is included by default.
I would like this to do the same thing in C++, but am worried that a user could (hypothetically) do a relative path include and cause a conflict.
Take for example, I use the flag like so: -I ../some/folder.
However then the user could simply type #include "../some/folder" to access the same content. Is there any way I can restrict this, and like the title of the question suggests, "protect" the folder from being called like that?
Furthermore, if there is a file inside of that folder called test.h and the user decides to create their own file called test.h locally and include it. How will the conflicts occur? Will it pick the local folder over the included via. flags?
An example of a basic implementation is as follows: (General syntax, no specific language)
boolean userDefine = false;
string defineName = "foo";
// Do something to determine if <> define or "" define.
if (userDefine) {
// Returns #include "foo"
return "#include \"" + defineName + "\"";
} else {
// Returns #include "stdlib/foo"
return "#include \"stdlib/" + defineName + "\"";
}
But then again, the user could include the folder so that it satisfies the first condition and still gain access.
It's pretty much the standard practice to put any #include files at the very beginning of the C++ source file, as the first order of business.
Of course, a #include can appear anywhere in the C++ source file, and there are situations when that happens but, if you were to grab some random C++ source from github, chances are pretty good that all the #include files will be at the beginning of the file.
So, all you have to do, is to make arrangements that your library's #include is always at the beginning, and use the standard #ifndef/#define guards in your header files. Then, manual inclusion of them subsequently will have no effect whatsoever, no matter what path is used.
Of course, this won't stop anyone from manually #undefing your guard, to create some chaos. However, C++ never had a reputation for reliably preventing you from shooting yourself in the foot, and is unlikely to earn that reputation in the foreseeable future; so what? Actually, most compilers implement #pragma once, which might be a slightly better foot self-shooting prevention approach...
I've got a C/C++ question, can I reuse functions across different object files or projects without writing the function headers twice? (one for defining the function and one for declaring it)
I don't know much about C/C++, Delphi and D. I assume that in Delphi or D, you would just write once what arguments a function takes and then you can use the function across diferent projects.
And in C you need the function declaration in header files *again??, right?. Is there a good tool that will create header files from C sources? I've got one, but it's not preprocessor-aware and not very strict. And I've had some macro technique that worked rather bad.
I'm looking for ways to program in C/C++ like described here http://www.digitalmars.com/d/1.0/pretod.html
Imho, generating the headers from the source is a bad idea and is unpractical.
Headers can contain more information that just function names and parameters.
Here are some examples:
a C++ header can define an abstract class for which a source file may be unneeded
A template can only be defined in a header file
Default parameters are only specified in the class definition (thus in the header file)
You usually write your header, then write the implementation in a corresponding source file.
I think doing the other way around is counter-intuitive and doesn't fit with the spirit of C or C++.
The only exception is can see to that is the static functions. A static function only appears in its source file (.cor .cpp) and can't (obviously) be used elsewhere.
While I agree it is often annoying to copy the header definition of a method/function to the source file, you can probably configure your code editor to ease this. I use Vim and a quick script helped me with this a lot. I guess a similar solution exists for most other editors.
Anyway, while this can seem annoying, keep in mind it also gives a greater flexibility. You can distribute your header files (.h, .hpp or whatever) and then transparently change the implementation in source files afterward.
Also, just to mention it, there is no such thing as C/C++: there is C and there is C++; those are different languages (which indeed share much, but still).
It seems to me that you don't really need/want to auto-generate headers from source; you want to be able to write a single file and have a tool that can intelligently split that into a header file and a source file.
Unfortunately, I'm not aware of any such tool. It's certainly possible to write one - but you'd need a given a C++ front end. You could try writing something using clang - but it would be a significant amount of work.
Considering you have declared some functions and wrote their implementation you will have a .c/cpp file and a header .h file.
What you must do in order to use those functions:
Create a library (DLL/so or static library .a/.lib - for now I recommend static library for the ease of use) from the files were the implementation resides
Use the header file (#include it) (you don't need to rewrite the header file again) in your programs to obtain the function definitions and link with your library from step 1.
Though >this< is an example for Visual Studio it makes perfect sense for other development environments also.
This seems like a rudimentary question, so assuming I have not mis-read,
Here is a basic example of re-use, to answer your first question:
#include "stdio.h"
int main( int c, char ** argv ){
puts( "Hello world" );
}
Explanation:
1. stdio.h is a C header file containing (among others) the definition of a function called puts().
2. in main, puts() is called, from the included definition.
Some compilers (including gcc I think ) have an option to generate headers.
There is always very much confusion about headers and source-files in C++. The links I provided should help to clear that up a little.
If you are in the situation that you want to extract headers from source-file, then you probably went about it the wrong way. Usually you first declare your function in a header-file, and then provide an implementation (definition) for it in a source-file. If your function is actually a method of a class, you can also provide the definition in header file.
Technically, a header file is just a bunch of text that is actually inserted into the source file by the preprocessor:
#include <vector>
tells the preprocessor to insert contents of the file vector at the exact place where the #include appears. This really just text-replacement. So, header-files are not some kind of special language construct. They contain normal code. But by putting that code into a separate file, you can easily include it in other files using the preprocessor.
I think it's a good question which is what led me to ask this: Visual studio: automatically update C++ cpp/header file when the other is changed?
There are some refactoring tools mentioned but unfortunately I don't think there's a perfect solution; you simply have to write your function signatures twice. The exception is when you are writing your implementations inline, but there are reasons why you can't or shouldn't always do this.
You might be interested in Lazy C++. However, you should do a few projects the old-fashioned way (with separate header and source files) before attempting to use this tool. I considered using it myself, but then figured I would always be accidentally editing the generated files instead of the lzz file.
You could just put all the definitions in the header file...
This goes against common practice, but is not unheard of.
How do I turn one file with lots of classes to many files with one class per file? (C\C++)
So I have that file with such structure: Some includes and then lots of classes that sometimes call each other:
#include <wchar.h>
#include <stdlib.h>
//...
class PG_1 {
//...
}
class PG_2 {
//...
}
//......
class PG_N {
//...
}
If you're not using revision control (tsk tsk):
Back up your entire project in case you mess up.
Cut and paste each class into its own classname.h and classname.cpp files. Replace classname with the name of the class. Update the include guards.
Add the #include directives that you think are necessary for each class's dependencies.
Delete multiclass.h and multiclass.cpp.
Add the single-class files to your project or makefile. Remove the multi-class files from your project or makefile.
Build the project or makefile.
If it fails to build, fix the problem (e.g. a missing #include) and go to step 6.
Once it builds, run your tests.
If the tests fail, diagnose and fix the problem, and go to step 6.
If you are using a revision control system that supports file-level branching (such as Perforce, or maybe Subversion?), you should take care to preserve the revision history, so that other developers can find old changes:
Do the rest of these steps in a development branch, not the trunk.
For each class name in multiclass.h and multiclass.cpp, integrate multiclass.h and multiclass.cpp into a separate classname.h and classname.cpp for that class.
Submit a changelist containing all of these integrations. This makes N copies of the original file, and they all have a revision history pointing to the original.
Check each new file out for edit.
Remove everything from each new file except the code that is needed for that particular class, and update the include guards.
Add the #include directives that you think are necessary for each class's dependencies.
Check the old multiclass.h and multiclass.cpp out for delete.
Check out the project or makefile for edit.
Add the single-class files to your project or makefile. Remove the multi-class files from your project or makefile.
Build the project or makefile.
If it fails to build, fix the problem (e.g. a missing #include) and go to step 10.
Once it builds, run your tests.
If the tests fail, diagnose and fix the problem, and go to step 10.
Submit the changelist with all of the edits.
If you are using a revision control system that doesn't support file-level branching, then some combination of the two methods should work. Hopefully you get the idea.
How do I turn one file with lots of
classes to many files with one class
per file?
Edit: Something I should mention on refactoring in general. There's no such thing as a big step in refactoring (not unless you want to destroy your code-base). You should always make transactional transformations to the code, with validity checks in between (transactional means they are clearly delimited and can be committed and rolled-back at any point). If you have big steps that means you haven't broken them enough into small steps. Also, each step should do one thing and one thing only. (end edit).
Steps:
back up everything (all affected files)
This means perform a commit in your source-control system. If you don't use any source control, install mercurial before continuing (go ahead, we'll wait ;)) - you can thank me later :D
create new files (.h and .cpp file) for the first class you want to remove, then include the new .h file in your old header (the one with many classes).
move the class declaration in the .h file and the class implementation in the new .cpp file.
remove the declaration / implementation from the old file. At this point compile the code, and copy #include dirrectives from the old files to the new files until everything compiles. At this point you should have your class moved to separate files, and included in the old header file. Do not copy all includes, only enough for your moved class to compile correctly.
compile the code (eventually run the application and make sure everything runs).
perform a commit in your source control system.
remove the included new file from your old (multiple classes) header file and compile. go through the code and include the new file in whatever files you get errors.
repeat the steps 5 and 6.
pick new class, go back to step 1.
Possible mistakes and caveats:
you may be tempted to make other changes to the new code while moving it to new files. Do not make any changes. At the end of a cycle (after step 8) you should have the same code you had before step 1, just in different files. Any changes you make to the code in between the steps will be difficult to separate from the refactoring, difficult to track later and difficult to reverse. It's not worth the hassle, especially when you can make the same changes once the refactoring cycle is completed (with no other problems).
you may be tempted to work on multiple classes at the same time. Don't do that either. If you work in cycles you are always able to revert the code (in your SCM) to versions of the code that worked and you have modular changes. It is also very easy to track changes and check you didn't introduce new bugs if you go one class at a time.
Sidenote: If you use a branching SCM you will be able to work on the tasks in parallel, to interrupt your refactoring (commit everything - let's call this "branch head A"), go back to the code before you started refactoring, make some other changes, commit those (call them "branch head B"), then go back to branch head A, finish your refactoring, then merge A and B and you're in business.
There are several ways to accomplish that.
The most straight forward would be to read the file one line at the time and detect if that line starts a class.
Then start detecting matching braces... you know if you find { +1 and } -1 until you reach zero. Yes, there's more to that, but that's the main part.
Select that block and write it on another file.
On the other hand, IF you're using Visual Studio, would be to create a macro and use the DTE to peruse the FileCodeModel of the currently open file, and create a file for each top level class in that.
Two basic coding style patterns are possible:
Class declarations in headers, member function/static data instantiation in .cpp files.
Class definitions with in-line implementation in headers
Option 2 may lead to code bloat since if you use the class in multiple compilation units you may get multiple copies of the implementation in the final link; it is down to the linker to eradicate this and it may or may not do so - YMMV. It also allows users of the class access to the implementation, which may be undesirable in some cases.
A combination of the two with simple getter/setter functions in-lined and larger code bodies in separate compilation units is an option. Often if I have a constructor that is entirely implemented by the initialiser list, I will include its empty body in-line.
Example for class cExampleClass:
cExampleClass.h
class cExampleClass
{
public:
cExampleClass() ;
~cExampleClass() ;
void memberfn() ;
} ;
cExampleClass.cpp
cExampleClass::cExampleClass()
{
// body
}
cExampleClass::~cExampleClass()
{
// body
}
void cExampleClass::memberfn()
{
// body
}
or in-lined:
cExampleClass.h
class cExampleClass
{
public:
cExampleClass()
{
// body
}
~cExampleClass()
{
// body
}
void memberfn()
{
// body
}
} ;
In both cases any source file that then uses cExampleClass simply includes the cExampleClass.h, and cExampleClass.cpp (if it exists) is separately compiled and linked.
Note that if the class includes static data member variables, these must be instantiated in a separate compilation unit in order for there to be just one common instance. Example:
cExampleClass.h
class cExampleClass
{
public :
static int staticmember ;
} ;
cExampleClass.cpp
int cExampleClass::staticmember = 0xffff ;
Do you know how to do it manually? If you know, writing a program to do the same thing is straightforward.
There might not be an easy way to do this. The problem is you have to get the #includes right, split the code correctly to different header and cpp files, and if your classes have cyclic dependencies among themselves, you have to deal with them correctly, or better, try to resolve those dependencies to make them non-cyclic.
Best suggestion I can give you: first try to do this manually for two or three classes. Then decide what kind of physical class layout you need. Afterwards, try to write a program. Don't try to write a program unless you fully understand what to do.
By the way, how many classes/files do have?
EDIT: To get a better notion of what a good physical class-to-file layout may be, I suggest to read Large Scale C++ Design from John Lakos. Is a little bit outdated, since it contains nothing about precompiled headers, but still useful.
I suggest writing a script (in your favorite scripting language) to extract the class declarations into their own file. If you're not good at scripting languages, you can always write a C++ program to extract the class declarations.
Another possibility may be to use an IDE with refactoring capabilities or a refactoring application. I have never used these, so I can't advise on their capabilities.
I have a static library that I am building in C++. I have separated it into many header and source files. I am wondering if it's better to include all of the headers that a client of the library might need in one header file that they in turn can include in their source code or just have them include only the headers they need? Will that cause the code to be unecessary bloated? I wasn't sure if the classes or functions that don't get used will still be compiled into their products.
Thanks for any help.
Keep in mind that each source file that you compile involves an independent invocation of the compiler. With each invocation, the compiler has to read in every included header file, parse through it, and build up a symbol table.
When you use one of these "include the world" header files in lots of your source files, it can significantly impact your build time.
There are ways to mitigate this; for example, Microsoft has a precompiled header feature that essentially saves out the symbol table for subsequent compiles to use.
There is another consideration though. If I'm going to use your WhizzoString class, I shouldn't have to have headers installed for SOAP, OpenGL, and what have you. In fact, I'd rather that WhizzoString.h only include headers for the types and symbols that are part of the public interface (i.e., the stuff that I'm going to need as a user of your class).
As much as possible, you should try to shift includes from WhizzoString.h to WhizzoString.cpp:
OK:
// Only include the stuff needed for this class
#include "foo.h" // Foo class
#include "bar.h" // Bar class
public class WhizzoString
{
private Foo m_Foo;
private Bar * m_pBar;
.
.
.
}
BETTER:
// Only include the stuff needed by the users of this class
#include "foo.h" // Foo class
class Bar; // Forward declaration
public class WhizzoString
{
private Foo m_Foo;
private Bar * m_pBar;
.
.
.
}
If users of your class never have to create or use a Bar type, and the class doesn't contain any instances of Bar, then it may be sufficient to provide only a forward declaration of Bar in the header file (WhizzoString.cpp will have #include "bar.h"). This means that anyone including WhizzoString.h could avoid including Bar.h and everything that it includes.
In general, when linking the final executable, only the symbols and functions that are actually used by the program will be incorporated. You pay only for what you use. At least that's how the GCC toolchain appears to work for me. I can't speak for all toolchains.
If the client will always have to include the same set of header files, then it's okay to provide a "convience" header file that includes others. This is common practice in open-source libraries. If you decide to provide a convenience header, make it so that the client can also choose to include specifically what is needed.
To reduce compile times in large projects, it's common practice to include the least amount of headers as possible to make a unit compile.
what about giving both choices:
#include <library.hpp> // include everything
#include <library/module.hpp> // only single module
this way you do not have one huge include file, and for your separate files, they are stacked neatly in one directory
It depends on the library, and how you've structured it. Remember that header files for a library, and which pieces are in which header file, are essentially part of the API of the library. So, if you lead your clients to carefully pick and choose among your headers, then you will need to support that layout for a long time. It is fairly common for libraries to export their whole interface via one file, or just a few files, if some part of the API is truly optional and large.
A consideration should be compilation time: If the client has to include two dozen files to use your library, and those includes have internal includes, it can significantly increase compilation time in a big project, if used often. If you go this route, be sure all your includes have proper include guards around not only the file contents, but the including line as well. Though note: Modern GCC does a very good job of this particular issue and only requires the guards around the header's contents.
As to bloating the final compiled program, it depends on your tool chain, and how you compiled the library, not how the client of the library included header files. (With the caveat that if you declare static data objects in the headers, some systems will end up linking in the objects that define that data, even if the client doesn't use it.)
In summary, unless it is a very big library, or a very old and cranky tool chain, I'd tend to go with the single include. To me, freezing your current implementation's division into headers into the library's API is bigger worry than the others.
The problem with single file headers is explained in detail by Dr. Dobbs, an expert compiler writer. NEVER USE A SINGLE FILE HEADER!!! Each time a header is included in a .cc/.cpp file it has to be recompiled because you can feed the file macros to alter the compiled header. For this reason, a single header file will dramatically increase compile time without providing any benifit. With C++ you should optimize for human time first, and compile time is human time. You should never, because it dramatically increases compile time, include more than you need to compile in any header, each translation unit(TU) should have it's own implementation (.cc/.cpp) file, and each TU named with unique filenames;.
In my decade of C++ SDK development experience, I religiously ALWAYS have three files in EVERY module. I have a config.h that gets included into almost every header file that contains prereqs for the entire module such as platform-config and stdint.h stuff. I also have a global.h file that includes all of the header files in the module; this one is mostly for debugging (hint enumerate your seams in the global.h file for better tested and easier to debug code). The key missing piece here is that ou should really have a public.h file that includes ONLY your public API.
In libraries that are poorly programmed, such as boost and their hideous lower_snake_case class names, they use this half-baked worst practice of using a detail (sometimes named 'impl') folder design pattern to "conceal" their private interface. There is a long background behind why this is a worst practice, but the short story is that it creates an INSANE amount of redundant typing that turns one-liners into multi-liners, and it's not UML compliant and it messes up the UML dependency diagram resulting in overly complicated code and inconsistent design patterns such as children actually being parents and vice versa. You don't want or need a detail folder, you need to use a public.h header with a bunch of sibling modules WITHOUT ADDITIONAL NAMESPACES where your detail is a sibling and not a child that is in reatliy a parent. Namespaces are supposed to be for one thing and one thing only: to interface your code with other people's code, but if it's your code you control it and you should use unique class and funciton names because it's bad practice to use a namesapce when you don't need to because it may cause hash table collision that slow downt he compilation process. UML is the best pratice, so if you can organize your headers so they are UML compliant then your code is by definition more robust and portable. A public.h file is all you need to expose only the public API; thanks.