Adding namespace name to source filename?

[Steve Folly]

Hi,

I know (hope!) we all follow good practice here and name our source files
with the name of the class it defines. i.e. A.h defines class A, and A.cpp
defines the methods for class A.

Lately, I've been pondering the merits or otherwise of including the
namespace name in the file name as well. Our source code library is growing
in size at work, and a few libraries are starting to clash on names, and
getting the include paths right is tricky.

For example - say we have a class Factory in namespace GUI, and in a
different library, also a class Factory in namespace Database. One would
expect there to be 2 Factory.h files that could be found in the include path
- which one gets included would depend on the order the include paths. I've
started to sort out these clashes by renaming them GUIFactory.h and
DatabaseFactory.h.

Other similar situations include name clashes with standard library headers,
and clashes even within the same library (e.g. If GUI::Factory and
Database::Factory are in the same library).

I've avoided renaming existing files just for the hell of it, but I'm
thinking of using this style for all new files, even where there may be no
possibility of name clashes.

I know this might sound really petty, but it has highlighted these name
clash problems and I wondered if anyone here has some 'best practice' tips
for this sort of thing?

Thanks.

--
Regards,
Steve

"...which means he created the heaven and the earth... in the DARK! How good
is that?"

 

[Alf P. Steinbach]

* Steve Folly:

Hi,

I know (hope!) we all follow good practice here and name our source files
with the name of the class it defines. i.e. A.h defines class A, and A.cpp
defines the methods for class A.

Lately, I've been pondering the merits or otherwise of including the
namespace name in the file name as well. Our source code library is growing
in size at work, and a few libraries are starting to clash on names, and
getting the include paths right is tricky.

For example - say we have a class Factory in namespace GUI, and in a
different library, also a class Factory in namespace Database. One would
expect there to be 2 Factory.h files that could be found in the include path
- which one gets included would depend on the order the include paths. I've
started to sort out these clashes by renaming them GUIFactory.h and
DatabaseFactory.h.

Other similar situations include name clashes with standard library headers,
and clashes even within the same library (e.g. If GUI::Factory and
Database::Factory are in the same library).

I've avoided renaming existing files just for the hell of it, but I'm
thinking of using this style for all new files, even where there may be no
possibility of name clashes.

I know this might sound really petty, but it has highlighted these name
clash problems and I wondered if anyone here has some 'best practice' tips
for this sort of thing?

A common practice is to map namespaces to directories (folders).

Not all namespaces, but the large ones.

For example, to include the file that declares boost::shared_ptr, you do

#include <boost/shared_ptr.hpp>

This means that a library directory structure typically repeats the
library name, if that name is also the library's main namespace name,

boost/
some_other_directory/
boost/

so that you direct your compiler to search for include files in the
outer boost directory, then it finds [boost/shared_ptr.hpp] in the inner
boost directory.

Cheers, & hth.,

- Alf

 

[werasm]

Lately, I've been pondering the merits or otherwise of including the
namespace name in the file name as well. Our source code library is growing
in size at work, and a few libraries are starting to clash on names, and
getting the include paths right is tricky.

I usually use the library name as "folder" identifier. Something that
I've
stolen with my eyes from boost . Therefore, all my libraries would
live in a root directory, which would be in my project include path.

I would then include like this:

<libname/component.hpp>

Usually the component does not live under libname, but component.hpp
is
only a forward include file to the real file. This way the physical
(or
directory) structure of the underlying library may change without the
application being aware of it. The real (header) file can move
around,
and the forward include file always points to the last position (I see
the
forward include file as an interface to the library structure). Even
the source files in the library make use of forward includes, and
never include it's own headers directly e.g. Never do "MyHeader.h".

Another thing that could be mentioned is that if all your object
files compile to one directory, you would have to discern using
more than just the directory names (or name your files as you
suggested, or use libraries, provided components with similar names
does not exist within a library). We use Eclipse's managed make
projects. They compile the object files in a parallel directory
structure that looks exactly like the source structure, and link
from this directory structure. Therefore this allows for file
names being the same, as long as they live in various directories
in the source.

Of course in the case where file names represent class names, you
have to map namespaces to directories, else you have multiple
definitions of a class with the same name.

For example - say we have a class Factory in namespace GUI, and in a
different library, also a class Factory in namespace Database. One would
expect there to be 2 Factory.h files that could be found in the include path
- which one gets included would depend on the order the include paths. I've
started to sort out these clashes by renaming them GUIFactory.h and
DatabaseFactory.h.

Our structure would look like this:

Libraries/{Specified in project include path}
Libname/
/Include
/Gui
Factory.h
/Database
Factory.h

/Source
/Gui
Factory.cpp
/Database
Factory.cpp

/. {Libname/}
GuiFactory.hpp --> Gui/Factory.h
DatabaseFactory.hpp --> Database/Factory.h

Therefore, this seems very similar to what you've mentioned
in terms of Gui and Database being prepended.

The forward include files have
another benefit that it provides an additional
level of include guards that causes less parsing
(Large Scale C++ Development by Lakos makes mention
of something similar achieved with external include
guards).

The structure here above we use for our libraries. For
the actual application we always use the folder as
identifier during including, for example:

"../Folder/Filename.h" where folder represents a
package, but not necessarily a namespace. If you
know the project will be very big and the likelihood
of name clashes are a concern, then I would use namespaces,
but we usually put an application in its own namespace,
and each library in its own. In the past we've mapped
namespaces to folders, but I've found this excessive
for our projects.

Kind regards,

Werner

 

[Craig Scott]

Hi,

I know (hope!) we all follow good practice here and name our source files
with the name of the class it defines. i.e. A.h defines class A, and A.cpp
defines the methods for class A.

Lately, I've been pondering the merits or otherwise of including the
namespace name in the file name as well. Our source code library is growing
in size at work, and a few libraries are starting to clash on names, and
getting the include paths right is tricky.

For example - say we have a class Factory in namespace GUI, and in a
different library, also a class Factory in namespace Database. One would
expect there to be 2 Factory.h files that could be found in the include path
- which one gets included would depend on the order the include paths. I've
started to sort out these clashes by renaming them GUIFactory.h and
DatabaseFactory.h.

Other similar situations include name clashes with standard library headers,
and clashes even within the same library (e.g. If GUI::Factory and
Database::Factory are in the same library).

I've avoided renaming existing files just for the hell of it, but I'm
thinking of using this style for all new files, even where there may be no
possibility of name clashes.

I know this might sound really petty, but it has highlighted these name
clash problems and I wondered if anyone here has some 'best practice' tips
for this sort of thing?

As others have suggested, using directory names which map to
namespaces is common and we found that it works well for us (large
multi-module code base). Something else to be aware of though is the
names you use for header guards in your include files. Many people use
the name of the header as the symbol they define, but if you have
multiple files with the same name, you can get some frustrating
compilation errors which can be hard to trace. We found that using the
namespace in the header guard symbol along with the class it defines
is a good approach. For example, for a file defining a class called
FooBar in namespace Barry:

#ifndef BARRY_FOOBAR_H
#define BARRY_FOOBAR_H

namespace Barry
{
// ....
}

There's the odd rare occasion where you have to do something else,
such as if the file only contains prototypes for free functions, but
usually you can come up with something sensible and fairly
predictable.

 

[James Kanze]

And how do you name a header which contains a set of functions,
rather than a class? Or the different source files when the
functions aren't virtual (and you have one function per source
file, because you're writing a library, and that's the
granularity of most linkers)?

[...]

As others have suggested, using directory names which map to
namespaces is common and we found that it works well for us (large
multi-module code base). Something else to be aware of though is the
names you use for header guards in your include files. Many people use
the name of the header as the symbol they define, but if you have
multiple files with the same name, you can get some frustrating
compilation errors which can be hard to trace. We found that using the
namespace in the header guard symbol along with the class it defines
is a good approach. For example, for a file defining a class called
FooBar in namespace Barry:

#ifndef BARRY_FOOBAR_H
#define BARRY_FOOBAR_H

namespace Barry
{
// ....
}

Header guards aren't meant for human's to read, so you might as
well do it right: my header guards currently look something
like:

#ifndef GB_ParsableString_hh_20061203ZaouMowehKWmObobAfKobWSc

The GB_ is a prefix designating global symbols from my library:
historically, it dates to before namespaces, when all symbols at
global scope were prefixed with it. Today, I still use it for
symbols which aren't in the library namespace, and that includes
macros.

The ParsableString_hh is derived from the name of the file, by
mapping all non-alphanumeric characters in the name to '_'.
What follows starts with the date the file was created, followed
by a number of purely random characters (generated by reading
from /dev/random... which means that I cannot create such files
under Windows.)

Obviously, my editor is set up to generate all of this
automatically, when I open a new header file.

There's the odd rare occasion where you have to do something
else, such as if the file only contains prototypes for free
functions, but usually you can come up with something sensible
and fairly predictable.

That's probably sufficient, but at least for libraries, I prefer
to play it safe, and throw in the random elements.