Boost logo

Boost :

Subject: Re: [boost] Name of namespace detail
From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2009-10-13 11:13:44


Neil Groves wrote:
> Hi,
>
> 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.

In this particular example, ZipFileReader is an internal startegy type
accessible through FileReader. I'm sorry for lack of precision.
IOW, FileReader can be a handle to Zip or BZip reader Body.

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

Now I see, why good naming in software craft is a difficult art.
I agree, but things may have different (so is understanding)
meaning for different people.

>> 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?

I have not seen any. It's just a discussion on pros and cons, I believe.

> If neither of these things have happened then it doesn't seem wise to focus
> effort improving this idiom.

Yes.

Just to clarify, you call "namespace detail" as idiom here, right?

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

As I tried to clarify above, ZipFileReader lives in private space,
most likely in namespace detail (or private_). It's my bad, I gave
slightly incomplete example.

Best regards,

-- 
Mateusz Loskot, http://mateusz.loskot.net

Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk