Boost logo

Boost :

Subject: Re: [boost] Name of namespace detail
From: Neil Groves (neil_at_[hidden])
Date: 2009-10-13 04:42:20


My opinions are made inline...

On Tue, Oct 13, 2009 at 9:20 AM, Mateusz Loskot <mateusz_at_[hidden]> wrote:

> Joel de Guzman wrote:
>> Mateusz Loskot wrote:
>>> Hi,
>>> Inspired by Jean-Louis question about what to put to namespace detail, I
>>> would be interested learning about rationale of name of the namespace
>>> detail (sometimes details or impl too).
>>> Recently, I've participated in a very interesting discussion, on ACCU
>>> members mailing list, about prefixes and suffixes like Base or _base nad
>>> Impl or _impl, as misused, irrelevant and confusing, meaningless, etc.
>>> For example, how to properly name elements of PIMPL idiom and similar.
>>> During the discussion I suggested that 'detail' is a good name for
>>> namespace dedicated to implementation details being not a part of public
>>> interface of a component. I got answer that it as the same issues (it's
>>> meaningless) as Impl etc.
>> Why? Could you please provide details on what their responses are?
> The discussion was too long I think (archives are not public) but generally
> the conclusion was that impl and base suffixes do not carry much
> information.
> For example that I put under discussion, the PIMPL-based FileReader
> using Impl suffixes etc.:
> class Reader
> {
> const std::auto_ptr<ReaderBase> pimpl_;
> public:
> // ...
> };
> class ZipReaderImpl : public ReaderBase {...};
> class BZipReaderImpl : public ReaderBase {...};
> we came to the improved version:
> class FileReader
> {
> class Body;
> const std::auto_ptr<Body> handle;
> public:
> // ...
> };
> class ZipFileReader : public FileReader::Body {...};
> class BZipFileReader : public FileReader::Body {...};
> I agree that the latter is more verbose telling what is what,
> and placing elements better regarding concepts it uses (handle-body).
> The ZipFileReader is now less obviously something I should not be using, in
my opinion.

> Given that, namespace detail was judged as similarly not much
> informative as Impl and Base suffix.
> It tells me I as a consumer of the library should not be using it, and that
is all it should be telling me. It is a neat orthogonal description nicely
separated from other names.

> On the other hand, all this is based on actual convention used in a
> project. If team members agree and understand what 'detail' means,
> then I can't see anything wrong with using it.
> Though, namespace private_ (with underscore), sounds a little bit better.
> Perhaps private_ is better, but then there are those that would argue that
a separate idiom should have a separate name. It is different because
ultimately you do have access to it, and it is open for extension.

> I hope it clarifies the point.

Has there ever been any evidence that maintenance was more difficult with
the detail namespace approach?
Have there been defects caused by the namespace detail approach?
If neither of these things have happened then it doesn't seem wise to focus
effort improving this idiom.

To be honest, I don't see how ZipFileReader is less clearly something I
shouldn't be using despite it playing the "Body" role. It was clearer in the
original that I should use the handle.

> Best regards,
> --
> Mateusz Loskot,
Neil Groves

Boost list run by bdawes at, gregod at, cpdaniel at, john at