Why are include directives on top of header files? - c++

I was once told in a programming class that C++ had achieved a better readability by letting the programmer declare its variable anywhere in a function block. This way, the variables were grouped together with the section of the code that dealt with it.
Why don’t we do the same for includes?
Put differently, why is it discouraged to put the include file next to the definition that will actually use it?
parser::parser()
{
// some initialization goes there which does not make use of regex
}
#include <boost/regex.hpp>
parser::start()
{
// here we need to use boost regex to parse the document
}

One of the reasons for this is that #include are context-less, they are just plain text inclusion, and having it in the middle of the code might have some unwanted effects. Consider for example that you had a namespace, and all your code in this file belongs to the namespace:
// Include on demand:
namespace ns {
void f() {} // does not need anything
//... lots of other lines of code
#include <vector>
void g() { std::vector<int> v; }
}
Now that might even compile fine... and wrong. because the inclusion is inside a namespace, the contents of the file are dumped inside ns and the included file declares/defines ::ns::std::vector. Because it is header only it might even compile fine, only to fail when you try to use that in an interface with a different subsystem (in a different namespace) -- This can be fixed, you only need to close all contexts, add the inclusion and reopen the same contexts...
There are other situations where the code in your translation unit might actually affect the includes. Consider, for example, that you added a using namespace directive in your translation unit. Any header included after that will have the using namespace directive in place, and that might also produce unwanted effects.
It could also be more error prone in different ways. Consider two headers that defined different overloads of f for int and double. You might add one (say the int version) towards the beginning of the file and use it, then add the other and use it. Now if you call f(5.0) above the line where the second header is included, the int version will be called --only overload available to the compiler at this point--, which would be a hard to catch error. The exact same line of code would have completely different meaning in different places in your file (admittedly that is already the case, but within the declarations in your file it is easier to find which is the one being picked up and why)
In general, the includes declare elements that you will be using in your component, and having them on the top provides a list of dependencies in a quick glance.

Imagine the following file:
#include <someheader>
namespace myns {
void foo() {
}
void bar() {
// call something from someheader:
func();
}
}
It might be tempting to put #include <someheader> nearer the point of usage. That would be fine iff you wrote the following instead:
namespace myns {
void foo() {
}
}
#include <someheader>
namespace myns {
void bar() {
// call something from someheader:
func();
}
}
The problem is in a medium/large sized file it's rather easy to loose track of quite how deeply nested you are inside namespaces (and other #ifdefs), depending on your indentation style. You might come back later and decide to move things around, or add another nested namespace.
So, if you write the #include at the top always you can never get bitten by accidentally writing something like:
namespace myns {
void foo() {
}
// Whoops, this shouldn't be inside myns at all!
#include <someheader>
void bar() {
// call something from someheader:
func();
}
}
which would be somewhere between wrong and very wrong depending on what exactly is in <someheader>. (You could for example end up with UB, by violating the ODR having multiple definitions which although otherwise legal and identical sequence of tokens match different functions and so violate § 3.2.5).

It's discouraged because most programmers are used to includes at the top of the file. Force of habit I think, and for consistency with 99% of existing code.
When I personally want to see what headers are included, I only look at the top. In special (and thankfully rare) cases where something is fishy, I might look for includes in the whole file.
To the compiler it makes no difference anyway.

Related

free function inside anonymous namespace

//file.h
namespace Foo{
namespace{
void func(){}
}
}
vs
namespace Foo{
void func(){}
}
//file2.cpp use file.h's method
What is the consequence (if there is one) in the calling code (in term of visiblity for example) between this two approach ?
This:
namespace Foo {
namespace {
void func() {}
}
}
Is largely equivalent to this:
namespace Foo {
static void func() {}
}
The difference is that in the static case, the function has internal linkage, so it is not visible to the linker. In the unnamed namespace case, the function has external linkage (is visible to the linker), but under a name which none of your other source files can "normally" access. You might still call the function from a different source file if you reverse-engineer the compiler's name mangling scheme, and the function is still listed among the object file's symbols, for example.
But the common point is that each source file which includes the code (perhaps by #includeing the header file) will contain its own copy of the function. This can have an impact on the size of your binary.
Also, if you need the first one for some reason, you should heavily document it. An unnamed namespace in a header file is generally a "WTF" point, and you do not want these in your code. I must say I can't think of a viable use case for this.
Both variants will allow the function to be found under the name Foo::func().
The compiler might generate different code in the two cases though. Declaring a function inside an anonymous namespace makes that function local to the .cpp file. That is, every .cpp file that includes the header might end up with their own (identical) instantiation of the code for func. This might lead to some bloat in the final executable, due to the duplicated code.
Note that if you define the function inline (as is suggested by your question) this is not really an issue, as the code will be duplicated anyway due to inlining.
Still, as pointed out in the comments: Anonymous namespaces in headers are unusual and will draw the suspicion of however reviews this code. You should always prefer the second option, unless you have very good reason not to.
The first is the equivalent of:
namespace Foo
{
namespace TranslationUnitSpecific
{
void func();
}
}
It means that every time you include the header, you declare
a new, unrelated instance of func. If func is not inline,
you would have to define it in every source file that uses it.
(On the other hand, it does mean that you can provide an
implementation in the header without making the function
inline.)
It also means that you cannot use the function in inline or
template functions defined in a header with risking undefined
behavior, due to violations of the one definition rule.
In general, there are very few, if any cases where you should
use an unnamed namespace in a header.

How to avoid multiple definition of function (Linux, GCC/G++, Code::Blocks)

I have a project in code blocks that uses many different files - quite often written by other programmers. At the moment I have a situation in which I have two different sub-projects containing function named in the same manner. Let's say: F(int x). So F(int x) is defined in two source files in two different locations and they have two different headers. Also I have created two different namespaces for those headers:
namespace NS1
{
extern "C"{
#include "header1definingF.h"
}
}
namespace NS2
{
extern "C"{
#include "header2definingF.h"
}
}
But still compiler complains that it has multiple definition of F(int x). How can I workaround this in Code::Blocks (In Visual Studio it works just fine).
EDIT: To be more clear those headers include C code. I haven't thought it will be so messy. There are like thousands of source files using other projects including thousands of functions again... so what to do. I have absolutely no idea how to make it work.
I wonder why it works on Visual Studio, but not on Code Blocks. This suggests you do have an include guard.
Does this help?
Project->Build options...->Linker settings (tab)
-Wl,--allow-multiple-definition
I can't understand your problems clearly, but i think you should understand how the compiler works, when you use gcc to compel your program, your program first will be run include operator, that means if you include a header, the compiler will copy the header file to the file. if you include the header twice there will be a twice define error.so you must guarantee once,you can use
#ifndef __FILE_NAME__
#define __FILE_NAME__
// your code
#endif
If your problem is the redefine the function, you should know how the compiler distinguish the function, i think your problem is you do not use the namespace when you use the function.
The problem is that the namespace do not work for C functions (extern "C").
Here is a simple sample which do not compile:
namespace NS1
{
extern "C"{
int f()
{
return 1;
}
}
}
namespace NS2
{
extern "C"{
int f()
{
return 2;
}
}
}
In this case the two functions are different but have the same name: f(). If you just declare the functions, it will compile but they must refer to the same function.
This second sample works fine. The functions have the name NS1::f() and NS2::f() which are differents.
namespace NS1
{
int f()
{
return 1;
}
}
namespace NS2
{
int f()
{
return 2;
}
}
If you want to use two different c code, you can use objcopy which can help you to have a NS1_f() and NS2_f() function. After that you should rename all functions of the libraries in your includes. In this case, no namespace are used. This is normal, there is no namespace in C. Equivalent functions:
int NS1_f()
{
return 1;
}
int NS2_f()
{
return 2;
}
Short of editing the .cpp files themselves and renaming the functions (which is not a practical solution), your options are either making sure to only include one of the header files with duplicate functions at a time (which could be a huge maintainance problem) or, and this would be my recommendation, make use of namespaces. They will save you a ton of hassle in this situation.
You may need one of two things. The following is called a Header Guard:
#ifndef MYHEADER_H
#define MYHEADER_H
//your header code goes here
#endif
This way the header is only included once per object file that asks for it. However, if you want to have two methods with the same identifier, they have to be part of different Namespaces:
namespace myspace1{
void func(void);
};
namespace myspace2{
void func(void);
};
Other than that, there's not really much else you can do. You shouldn't have two functions with the same name in general. Also, you would have to modify this in the header files that you mentioned.
You are allowed to declare functions as often as you want, however they can only have ONE definition.
I believe you have to edit cpp files as well to nest the two functions into a corresponding namespace. Plus, you have to choose which function you want to call like namespace::function() or you can use using namespace with either of the namespaces you created. Hope this helps!
[Updates #1] It is easier to get confused between the declaration and definition of a function. Remember that you can redeclare non-member functions. Thus, if a header file only contains non-member function declarations, it is safe to include it multiple times in one translation unit (a cpp file). Adding ifndef/define in a header file is a good habit for avoiding potential problems but that is not what resolves your problem.
Your problem is that you want to have two different function definitions with the same function signature(its name and arguments) and that's not allowed in C++. You can either change one of their signatures or put them into a different namespace (which you are trying but without touching their definitions). Both ways require you to edit files containing their definitions.
[Updates #2]
As you updated the question with that the code is in C, I've searched and found this:
What should I do if two libraries provide a function with the same name generating a conflict?
it will surely help you to understand your problem more clearly and find a solution. Good luck!

#includes within a namespace, to "embed" prewritten stuff in namespace

BRIEF: is it ever safe to do
namespace Foo {
#include "bar"
}
Before you blithely say no, I think I have some rules that allow it fairly safely.
But I don't like them, since they require the includer to separately include all global scope headers needed. Although this mightr be tolerable, if we imagine including within a namespace to be just a special management feature.
And overall, externs and forward declarations just don't work well from within namespaces.
So I gues I am asking
a) What other gotchas
b) is there a better way
== A [[Header-only library]] ==
I like writing libraries. [[Header-only libraries and linker libraries]].
E.g.
#include "Valid.hpp"
defines a template Valid, for a simple wrapper type.
(Don't get bogged down in "You should use some standard library for this rather than your own. This is an exanple. I dunno if Boost or C++ have yet standardized this. I have been using wrappers since templates were added to C++.)
Also, let us say, it is a header only library, that defines, in Valid.hpp,
a print function
std::string to_string( const Valid& v ) {
std::ostringstream oss;
if( v.valid() ) { oss << v; }
else { "invalid"; }
return oss.str();
}
And because I think it is the right thing to do,
I have Valid.hpp include the headers it depends on:
Valid.hpp:
#include <iostream>
#include <sstream>
template<typename T>
class Valid {
private:
T value_;
bool valid_
...
};
...
std::string to_string( const Valid<T>& v ) { ...
So far, so good.
I can use Valid straightforwardly.
== Name collision - trying to use include within namespace to work around ==
But sometimes there is a collision.
Sometimes somebody else has their own Valid.
Namespaces to the rescue, right? But I don't want to change all of my existing code to use the namespace.
So, I am tempted, in a new project that has a collision, to do
namespace AG {
namespace Wrapper {
#include "lib/AG/Wrapper/Valid.hpp"
}
}
AG::Wrapper::Valid<T> foo_v;
...
PROBLEM: the headers included are no longer freestanding. Everything defined inside is no placed inside
namespace AG::Wrapper.
It's not hard to "fix".
Al we "must" do is include all the top level libraries that Valid.hpp depends on.
If they have include guards, they will not be re-included.
#include <iostream>
#include <sstream>
namespace AG {
namespace Wrapper {
#include "lib/AG/Wrapper/Valid.hpp"
}
}
AG::Wrapper::Valid<T> foo_v;
...
But it is no longer freestanding. :-(
Worse, sometimes the header-only library contains extern declarations and forward declarations of stuff outside itself.
These declarations get placed inside the namespace too.
In particular, if the extern declarayion is inside a function defined in the namespace.
I.e. sometimes we use extern and forward declarations, rather than included an entire header file.
These get included in the namespace.
Q: is there a better way?
== :: doesn't do it ==
Hint: :: doesn't do it. At least not all the time, not in gcc 4.7.2.
(Gcc's behavior in this has changed over time. Gcc 4.1.2 behaved differently.)
E.g.
Type var;
namespace Foo {
void bar() {
extern ::Type ::var;;
extern ::Type ::Foo::bar;
extern ::Type::foo ::bar; // see the ambiguity?
};
But it's not just the ambiguity.
int var;
namespace Foo {
void bar() {
extern int var;
};
works - Foo::bar'svar is equal to ::var.
But it only works because of the declaration outside the namespace.
The following doesn't work
header
int var;
cpp
namespace Foo {
void bar() {
extern int var;
}
}
although the following does:
header
int var;
cpp
void bar() {
extern int var;
}
}
Basically, what this amounts to saying is that
it is not a trivial refactoring to put functions inside a namespace.
Wrapping a namespace around a chunk of code,
whether or not it is #include'd,
is not a sufficient.
... at least not if there are extern or forward declarations.
And even if you
== Opinion against putting includes within namespaces ==
Stackoverflow folks seem to be against putting #includes inside namespaces:
E.g. How to use class defined in a separate header within a namespace:
... you should never write a #include inside a namespace. Where "never" means, "unless you're doing something really obscure that I haven't thought of and that justifies it". You want to be able to look at a file, and see what the fully-qualified names are of all the things in it. You can't do that if someone comes along later and sticks an extra namespace on the front by including from inside their namespace. – Steve Jessop Jan 6 '12 at 16:38
Overall question:
Is there any way, from deep within a namespace,
to say "and now here are some names that I am depending on from the outside world, not within the namespace."?
I.e. I would like to be able to say
namespace A {
void foo() {
// --- here is a reference to gloal scope extreren ...
I know this is an old question, but I want to give a more detailed answer anyway. Also, give a real answer to the underlying problem.
Here's just a few things that can go wrong if you include a header from within a namespace.
The header includes other headers, which are then also included from within the namespace. Then a different place also wants to include these headers, but from outside the namespace. Because the headers have include guards, only one of the includes actually goes in effect, and the actual namespace of the stuff defined in the headers suddenly subtly depends on the order you include other headers.
The header, or any of its included headers, expects to be in the global namespace. For example, standard library headers will very often (in order to avoid conflicts) refer to other standard stuff (or implementation details) as ::std::other_stuff, i.e. expect std to be directly in the global namespace. If you include the header from within a namespace, that's no longer the case. The name lookup for this stuff will fail and the header will no longer compile. And it's not just standard headers; I'm sure there are some instances of this e.g. in the Boost headers too.
If you take care of the first problem by ensuring that all other headers are included first, and the second problem by making sure no fully qualified names are used, things can still go wrong. Some libraries require that other libraries specialize their stuff. For example, a library might want to specialize std::swap, std::hash or std::less for its own type. (You can overload std::swap instead, but you can't do that for std::hash and std::less.) The way to do this is close your library-specific namespace, open namespace std, and put the specialization there. Except if the header of the library is included in arbitrarily deeply nested namespaces, it cannot close those namespaces. The namespace std it attempts to open won't be ::std, but ::YourStuff::std, which probably doesn't contain any primary template to specialize, and even if it did, that would still be the wrong thing to do.
Finally, things in a namespace simply have different names than things outside. If your library isn't header-only but has a compiled part, the compiled part probably didn't nest everything in the namespace, so the stuff in the library has different names than the stuff you just included. In other words, your program will fail to link.
So in theory, you can design headers that work when included within a namespace, but they're annoying to use (have to bubble up all dependencies to the includer) and very restricted (can't use fully qualified names or specialize stuff in another library's namespace, must be header-only). So don't do it.
But you have an old library that doesn't use namespaces, and you want to update it to use them without breaking all your old code. Here's what you should do:
First, you add a subdirectory to your library's include directory. Call it "namespaced" or something like that. Next, move all the headers into that directory and wrap their contents in a namespace.
Then you add forwarding headers to the base directory. For each file in the library, you add a forwarder that looks like this:
#ifndef YOURLIB_LEGACY_THE_HEADER_H
#define YOURLIB_LEGACY_THE_HEADER_H
#include "namespaced/the_header.h"
using namespace yourlib;
#endif
Now the old code should just work the way it always did.
For new code, the trick is not to include "namespaced/the_header.h", but instead change the project settings so that the include directory points at the namespaced subdirectory instead of the library root. Then you can simply include "the_header.h" and get the namespaced version.
I don't think it's safe. You put all your includes into the namespace Foo...
Imagine some of your includes include something from the std namespace... I cannot imagine the mess !
I wouldn't do that.
Header files are not black boxes. You can always look at a header you're including in your project and see if it is safe to include it inside a namespace block. Or better yet, you can modify the header itself to add the namespace block. Even if the header is from a third-party library and changes in a subsequent release, the header you have in your project won't change.

How can I avoid including class implementation files?

Instead of doing
#include "MyClass.cpp"
I would like to do
#include "MyClass.h"
I've read online that not doing so is considered bad practice.
Separate compilation in a nutshell
First, let's get some quick examples out there:
struct ClassDeclaration; // 'class' / 'struct' mean almost the same thing here
struct ClassDefinition {}; // the only difference is default accessibility
// of bases and members
void function_declaration();
void function_definition() {}
extern int global_object_declaration;
int global_object_definition;
template<class T> // cannot replace this 'class' with 'struct'
struct ClassTemplateDeclaration;
template<class T>
struct ClassTemplateDefinition {};
template<class T>
void function_template_declaration();
template<class T>
void function_template_definition() {}
Translation Unit
A translation unit (TU) is a single source file (should be a **.cpp* file) and all the files it includes, and they include, etc. In other words: the result of preprocessing a single file.
Headers
Include guards are a hack to work around lack of a real module system, making headers into a kind of limited module; to this end, including the same header more than once must not have an adverse affect.
Include guards work by making subsequent #includes no-ops, with the definitions available from the first include. Because of their limited nature, macros which control header options should be consistent throughout a project (oddball headers like <assert.h> cause problems) and all #includes of public headers should be outside of any namespace, class, etc., usually at the top of any file.
See my include guard naming advice, including a short program to generate include guards.
Declarations
Classes, functions, objects, and templates may be declared almost anywhere, may be declared any number of times, and must be declared before referring to them in any way. In a few weird cases, you can declare classes as you use them; won't cover that here.
Definitions
Classes may be defined at most once[1] per TU; this typically happens when you include a header for a particular class. Functions and objects must be defined once in exactly one TU; this typically happens when you implement them in a **.cpp* file. However, inline functions, including implicitly inline functions inside class definitions, may be defined in multiple TUs, but the definitions must be identical.
For practical purposes[2], templates (both class templates and function templates) are defined only in headers, and if you want to use a separate file, then use another header[3].
[1] Because of the at-most-once restriction, headers use include guards to prevent multiple inclusion and thus multiple definition errors.
[2] I won't cover the other possibilities here.
[3] Name it blahblah_detail.hpp, blahblah_private.hpp, or similar if you want to document that it's non-public.
Guidelines
So, while I'm sure everything above is all a big ball of mud so far, it's less than a page on what should take up a few chapters, so use it as a brief reference. Understanding the concepts above, however, is important. Using those, here's a short list of guidelines (but not absolute rules):
Always name headers consistently in a single project, such as **.h* for C and **.hpp* for C++.
Never include a file which is not a header.
Always name implementation files (which are going to be directly compiled) consistently, such as **.c* and **.cpp*.
Use a build system which can compile your source files automatically. make is the canonical example, but there are many alternatives. Keep it simple in simple cases. For example, make can be used its built-in rules and even without a makefile.
Use a build system which can generate header dependencies. Some compilers can generate this with command-line switches, such as -M, so you can make a surprisingly useful system easily.
Build Process
(Here's the tiny bit that answers your question, but you need most of the above in order to get here.)
When you build, the build system will then go through several steps, of which the important ones for this discussion are:
compile each implementation file as a TU, producing an object file (**.o*, **.obj*)
each is compiled independently of the others, which is why each TU needs declarations and definitions
link those files, along with libraries specified, into a single executable
I recommend you learn the rudiments of make, as it is popular, well-understood, and easy to get started with. However, it's an old system with several problems, and you'll want to switch to something else at some point.
Choosing a build system is almost a religious experience, like choosing an editor, except you'll have to work with more people (everyone working on the same project) and will likely be much more constrained by precedent and convention. You can use an IDE which handles the same details for you, but this has no real benefit from using a comprehensive build system instead, and you really should still know what it's doing under the hood.
File Templates
example.hpp
#ifndef EXAMPLE_INCLUDE_GUARD_60497EBE580B4F5292059C8705848F75
#define EXAMPLE_INCLUDE_GUARD_60497EBE580B4F5292059C8705848F75
// all project-specific macros for this project are prefixed "EXAMPLE_"
#include <ostream> // required headers/"modules"/libraries from the
#include <string> // stdlib, this project, and elsewhere
#include <vector>
namespace example { // main namespace for this project
template<class T>
struct TemplateExample { // for practical purposes, just put entire
void f() {} // definition of class and all methods in header
T data;
};
struct FooBar {
FooBar(); // declared
int size() const { return v.size(); } // defined (& implicitly inline)
private:
std::vector<TemplateExample<int> > v;
};
int main(std::vector<std::string> args); // declared
} // example::
#endif
example.cpp
#include "example.hpp" // include the headers "specific to" this implementation
// file first, helps make sure the header includes anything it needs (is
// independent)
#include <algorithm> // anything additional not included by the header
#include <iostream>
namespace example {
FooBar::FooBar() : v(42) {} // define ctor
int main(std::vector<std::string> args) { // define function
using namespace std; // use inside function scope, if desired, is always okay
// but using outside function scope can be problematic
cout << "doing real work now...\n"; // no std:: needed here
return 42;
}
} // example::
main.cpp
#include <iostream>
#include "example.hpp"
int main(int argc, char const** argv) try {
// do any global initialization before real main
return example::main(std::vector<std::string>(argv, argv + argc));
}
catch (std::exception& e) {
std::cerr << "[uncaught exception: " << e.what() << "]\n";
return 1; // or EXIT_FAILURE, etc.
}
catch (...) {
std::cerr << "[unknown uncaught exception]\n";
return 1; // or EXIT_FAILURE, etc.
}
This is called separate compilation model. You include class declarations into each module where they are needed, but define them only once.
In addition to hiding implementation details in cpp files (check other replies), you can additionally hide structure details by class forward declaration.
class FooPrivate;
class Foo
{
public:
// public stuff goes here
private:
FooPrivate *foo_private;
};
The expression class FooPrivate says that FooPrivate is completely defined somewhere else (preferably in the same file where Foo's implementation resides, before Foo's stuff comes. This way you make sure that implementation details of Foo(Private) aren't exposed via the header file.
You needn't include .c or .cpp files - the compiler will compile them regardless whether they're #included in other files or not. However, the code in the .c/.cpp files is useless if the other files are unaware of the classes/methods/functions/global vars/whatever that's contained in them. And that's where headers come into play. In the headers, you only put declarations, such as this one:
//myfile.hpp
class MyClass {
public:
MyClass (void);
void myMethod (void);
static int myStaticVar;
private:
int myPrivateVar;
};
Now, all .c/.cpp files that will #include "myfile.hpp" will be able to create instances of MyClass, operate on myStaticVar and call MyClass::myMethod(), even though there's no actual implementation here! See?
The implementation (the actual code) goes into myfile.cpp, where you tell the compiler what all your stuff does:
//myfile.cpp
int MyClass::myStaticVar = 0;
MyClass::MyClass (void) {
myPrivateVar = 0;
}
void MyClass::myMethod (void) {
myPrivateVar++;
}
You never include this file anywhere, it's absolutely not necessary.
A tip: create a main.hpp (or main.h, if you prefer - makes no difference) file and put all the #includes there. Each .c/.cpp file will then only need to have have this line: #include "main.hpp". This is enough to have access to all classes, methods etc. you declared in your entire project :).
You should not include a source file (.c or .cpp). Instead you should include the corresponding header file(.h) containing the declarations. The source files needs to be compiled separately and linked together to get the final executable.
Cpp files should be defined in your compiler script to be compiled as object files.
What ide are you using?
I am going to assume you are compiling with gcc, so here is the command to compile two .cpp files into one executable
gcc -o myclasses.out myclass.cpp myotherclass.cpp
You should only use #include to include class definitions, not the implentation
One thing you will want to watch out for when including you class declarations from a .h/.hpp is make sure it only ever gets included once. If you don't do this you will get some possibly cryptic compiler errors that will drive you up the wall.
To do this you need to tell the compiler, using a #define, to include the file only if the #define does not already exist.
For example (MyClass.h):
#ifndef MYCLASS_H
#define MYCLASS_H
class MyClass
{
// Memebers and methods
}
#endif
// End of file
This will guarantee your class declaration only gets included once even if you have it included in many different .cpp files.

Shorten nested namespace names

If you use nested namespaces, declarations in header files can get very long and unreadable.
//header1
namespace test { namespace test1 {
class Test {};
} } //namespace
In header2 of the program:
#include "header1"
namespace test2 {
class Test1 {
void test(test::test1::Test &test) {}
void test1(test::test1::Test &test) {}
void test2(test::test1::Test &test1, test::test1::Test &test2) {}
};
}
Are there any possibilities to shorten the names in header2?
Here is my favorite technique:
#include "header1"
namespace test2 {
class Test1 {
private:
typedef ::test::test1::Test MeaningfulName;
void test(MeaningfulName &test) {}
void test1(MeaningfulName &test) {}
void test2(MeaningfulName &test1, MeaningfulName &test2) {}
};
}
I make my typedef aliases private, but I put them right at the beginning of the class declaration. It doesn't matter that they're private to the rest of the program because nobody will be using the aliased name, they will be using the actual type name or their own alias for the name.
I also really prefer to use anchored namespace names to avoid later surprises. My rule for this is that I always use an anchored name unless the namespace is one I control and/or is part of the current project or package or whatever. Then I will use the shortest possible relative name. If that relative name would start from the root namespace, I still often use an anchored name.
The main problem is the digraph <: which will crop up in template declarations a lot once you start using anchored names more often. You have to put in a space to avoid it, especially since digraph processing happens at a really early stage and can give you some very weird error messages.
you can alias namespaces, like this:
namespace tt=test::test1;
There are ways to shorten the names by using aliases or the using keyword, but they're almost always a bad idea. Namespaces exist for a reason, that reason is to keep things separated. As soon as you put the using keyword in a header file you break that separation, and there's no point in using namespaces at all. Inside your cpp files you can feel free to have using namespace test1 if you're implementing stuff in test1, but I would recomend you not do that in your header file as it is the same as putting it at the top of every single cpp file in which that header is included.
What you have to remember is that declaring something in a header is the same as declaring it in every cpp file in which that header is included. It would also be worth asking yourself, "If you're using test1 inside test2 so often, why are they different namespaces?"
In file header2.h
using namespace test::test1;
While this is an old question I feel like I should put forward my solution to this issue, particularly since it's one of the first results that pop-up in google for the subject and may help others.
This method is definitely not the safest as it involves using preprocessor directives but I've taken a liking to using #define and #undef to shorten namespaces in headers.
Here's an example:
#include "header1"
#define shortNS test::test1
namespace test2 {
class Test1 {
void test(shortNS::test &test) {}
void test1(shortNS::test &test) {}
void test2(shortNS::test &test1, shortNS::test &test2) {}
};
}
#undef shortNS
Basically it works by creating a define called "shortNS" that the preprocessor blindly replaces with "test::test1" where ever it occurs after the definition. The issue of course with defining a macro is that it's not limited by scope in any way shape or form, which can wreak havoc and has been known to cause any unsuspecting programmer to loose their mind whilst attempting to debug it.
So to prevent that once we're done with the define we #undef shortNS to tell the preprocessor to stop replacing "shortNS" with "test::test1". This allows us to simulate scope to some degree. In the example above I limited shortNS to the 'scope' of the file.
Here's a brief list of pros/cons off the top of my head.
Pros:
Allows you to manually limit scope. (Only need it for half a function? Sure.)
Transparent to anyone including the file.
No left-over namespace like with "namespace a = b::c"
No namespace collisions from "using namespace"
Doesn't bring a namespace into the current namespace (like "using namespace" does)
Cons:
Any errors in the definition of the shortened namespace will appear wherever it is used never at the macro itself.
If you include a file inside a #define #undef "block" the define will be used in the included file which may cause unintended results and/or headaches.
If you forget to #undef it can/will wreck havoc and you will go insane.
It's a little clunky.
People who are maintaining your code will hate you.
Long story short, if you're comfortable with macros and don't mind pulling your hair out trying to debug it when it goes wrong, go ahead. The preprocessor is a very, very powerful thing but it's like taping a bit of C4 to your foot and mashing the keypad to set the timer - you don't know when it's going to blow your leg off.