Adding namespace name to source filename?

Discussion in 'C++' started by Steve Folly, Sep 29, 2007.

  1. Steve Folly

    Steve Folly Guest

    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?"
     
    Steve Folly, Sep 29, 2007
    #1
    1. Advertising

  2. * 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

    --
    A: Because it messes up the order in which people normally read text.
    Q: Why is it such a bad thing?
    A: Top-posting.
    Q: What is the most annoying thing on usenet and in e-mail?
     
    Alf P. Steinbach, Sep 29, 2007
    #2
    1. Advertising

  3. Steve Folly

    werasm Guest

    On Sep 29, 6:37 pm, Steve Folly <> wrote:

    > 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
     
    werasm, Sep 29, 2007
    #3
  4. Steve Folly

    Craig Scott Guest

    On Sep 30, 2:37 am, Steve Folly <> wrote:
    > 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.

    --
    Craig Scott
    Computational Modeling, CSIRO (CMIS)
    Melbourne, Australia
     
    Craig Scott, Oct 1, 2007
    #4
  5. Steve Folly

    James Kanze Guest

    On Oct 1, 1:23 am, Craig Scott <> wrote:
    > On Sep 30, 2:37 am, Steve Folly <> wrote:
    > > 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.


    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.

    --
    James Kanze (GABI Software) email:
    Conseils en informatique orientée objet/
    Beratung in objektorientierter Datenverarbeitung
    9 place Sémard, 78210 St.-Cyr-l'École, France, +33 (0)1 30 23 00 34
     
    James Kanze, Oct 1, 2007
    #5
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. =?Utf-8?B?Sm9l?=

    Extract filename from a filename typed by user

    =?Utf-8?B?Sm9l?=, Aug 23, 2004, in forum: ASP .Net
    Replies:
    1
    Views:
    1,060
    Travis Murray
    Aug 24, 2004
  2. Replies:
    1
    Views:
    1,571
    Roland de Ruiter
    Jun 15, 2006
  3. Ed
    Replies:
    10
    Views:
    46,512
    alok000707
    Jul 13, 2010
  4. Beauregard T. Shagnasty

    Re: filename.gif or filename.gif.jpg?

    Beauregard T. Shagnasty, May 30, 2008, in forum: HTML
    Replies:
    1
    Views:
    792
    Jonathan N. Little
    May 30, 2008
  5. Bergamot
    Replies:
    0
    Views:
    473
    Bergamot
    May 30, 2008
Loading...

Share This Page