The POCO C++ Libraries Blog

Namespaces, Again

Filed under: Uncategorized by guenter at 17:27

Today I made a change to the way namespaces in POCO are handled. First, I got rid of the unpopular namespace macros. Second, I introduced an outer Poco namespace.
The change was quite painless and with the help of Visual Studio’s Replace in Files function I was able do the complete change in about two hours (including building and running the testsuites).

For the namespace syntax, I chose same style as in Boost. This means that namespace blocks are not indented, and the way the braces are placed is different than the way the Coding Styleguide suggests. Instead of Foundation_BEGIN and Foundation_END we now have

namespace Poco {
namespace XML {

class ...

} } // namespace Poco::XML

This seems like a good compromise between readability and style.
Unless there are major objections, I plan to put the changes into 1.2. I will probably also add some kind of backwards compatibility switch in the form of a using namespace Poco; in Foundation/Foundation.h if a certain preprocessor macro (POCO_USE_POCO_NAMESPACE) is defined.

I am thinking about getting rid of the Foundation namespace alltogether. So, everything in the Foundation library will be directly in the Poco namespace, while the other library will use two namespaces (Poco::XML, Poco::Util, Poco::Net). I think this makes sense, because Foundation is the “heart” of Poco, and all other libraries depend on it. Boost does it similar. Also, shorter namespaces make the code more readable (Poco::Foundation::BufferedBidirectionalStreamBuf really is quite long).
Also, I am thinking about changing the directory hierarchy for header files, by introducing a Poco top-level directory. This will again sync namespaces to include file hierarchies, so we have
#include “Poco/BinaryWriter.h” for Poco::BinaryWriter
#include “Poco/Net/HTTPClientSession.h” for Poco::Net::HTTPClientSession.

The only downside is that this will break existing code and require a global search/replace session. However, my own experience with our quite expensive codebase shows that this can be done quite easily. I really want to put this into 1.2, because the longer we wait with breaking changes, the more damage will result.

  1. These changes sound excellent to me. 🙂

    Comment by Andrew Marlow on August 15, 2006, 17:10

  2. I have just began looking at Poco.
    Foundation is kind of verbose. I was thinking why not ‘base’.
    And ‘poco’ instead of ‘Poco’

    Comment by Anthony on August 15, 2006, 19:21

  3. I’m OK with it (especially with dropping Foundation).

    Comment by alex on August 15, 2006, 21:13

  4. I have switched all of Poco, as well as some of our proprietary libs to the new namespace and headers scheme. The transition has been quite smooth – global search/replace is all that’s needed, and I really like the result so far. After some tests on more platforms I will release a new preview of 1.2 later today (or tomorrow, latest).

    To sum it up:

    • The Foundation namespace is now just Poco.
    • XML, Util and Net have become Poco::XML, Poco::Util and Poco::Net.
    • #includes are now in the form #include “Poco/Foundation.h” for Foundation headers and #include “Poco/XML/XML.h” for other libs.

    Comment by guenter on August 16, 2006, 07:45

  5. Did Poco have commercial customers before going open source?
    My initial impression was that this was a stable commercial library that was already widely used that has now been open sourced.
    With changes as significant as you have just made what happnes to exisiting code?
    I have no issue with the change since I am just beginnig to check the library out but am wondering how long time users will react to these changes.


    Comment by Fred on August 16, 2006, 15:55

  6. We’ll handle this on a case-by-case basis, which might include maintaining two parallel versions for some time…

    Experience with our own codebase shows that the change can be made with a few global search/replace operations and is a matter of a few hours at most, so I think it’s not that much of a problem.

    Comment by guenter on August 16, 2006, 16:28

  7. This is just a response to comment # 2.

    The reason for ‘Poco’ and not ‘poco’ is naming convention. I would guess the developer(s) are trying to differentiate the class name from regular variable names. It’s common pratice once you get into it.

    Comment by Gypsy1 on August 17, 2006, 00:46

RSS RSS feed for comments on this post. TrackBack URI

Leave a comment