Name of namespace detail
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. It raised some questions for myself, being interested in improving my craft, I would like to learn better about the name of namespace detail. I use detail name myself. Any better names for bucket with implementation details? Best regards, -- Mateusz Loskot, http://mateusz.loskot.net Charter Member of OSGeo, http://osgeo.org
I use detail name myself. Any better names for bucket with implementation details?
What about `namespace private_` ? Even if access won't be controlled by the compiler. And also a `namespace protected_` if there are useful things to put there ? Btw fusion has an `extension` namespace in addition to `detail`. It seems to play the same role as protected interfaces in class hierarchies. J-L
Jean-Louis Leroy wrote:
I use detail name myself. Any better names for bucket with implementation details?
What about `namespace private_` ? Even if access won't be controlled by the compiler.
That's my favourite replacement. The underscore suffix in name could be easily linked with quite popular use of it in naming private class members: struct T { private: int value_; int foo_() { ... } }
And also a `namespace protected_` if there are useful things to put there ?
Doesn't really work for me. If something is useful (assuming for a library client), put it to public namespace. Second would be too much, convention became too complex, so vague. I think. Best regards, -- Mateusz Loskot, http://mateusz.loskot.net Charter Member of OSGeo, http://osgeo.org
Am Tuesday 13 October 2009 01:57:16 schrieb Mateusz Loskot:
Jean-Louis Leroy wrote:
I use detail name myself. Any better names for bucket with implementation details?
What about `namespace private_` ? Even if access won't be controlled by the compiler.
That's my favourite replacement.
how is "private" more meaningful than "detail"? private is a keyword defined by c++. detail is a namespace defined by boost. both names aren't meaningful or descriptive unless you know their definition. (.NET actually uses "private" and "public" and enforces it)
Jean-Louis Leroy wrote:
I use detail name myself. Any better names for bucket with implementation details?
What about `namespace private_` ? Even if access won't be controlled by the compiler.
I don't care for that only because the privacy isn't enforced and because the name has to be doctored to avoid the keyword. OTOH, perhaps you could submit that as a feature request for the next version of the standard. That is, suggest that "namespace private detail" be like an unnamed namespace, but with the facilities offered by a named namespace (scope resolution, using declarations, etc.).
And also a `namespace protected_` if there are useful things to put there ?
That one doesn't make any sense to me. _____ Rob Stewart robert.stewart@sig.com Software Engineer, Core Software using std::disclaimer; Susquehanna International Group, LLP http://www.sig.com IMPORTANT: The information contained in this email and/or its attachments is confidential. If you are not the intended recipient, please notify the sender immediately by reply and immediately delete this message and all its attachments. Any review, use, reproduction, disclosure or dissemination of this message or any attachment by an unintended recipient is strictly prohibited. Neither this message nor any attachment is intended as or should be construed as an offer, solicitation or recommendation to buy or sell any security or other financial instrument. Neither the sender, his or her employer nor any of their respective affiliates makes any warranties as to the completeness or accuracy of any of the information contained herein or that this message or any of its attachments is free of viruses.
And also a `namespace protected_` if there are useful things to put there ?
That one doesn't make any sense to me.
An example would be a namespace containing templates to be specialized to make a lib support new types. Most users won't want to sip in them names when they say `using namespace thelib` so it's not public; it's not private either... J-L
Jean-Louis Leroy wrote:
An example would be a namespace containing templates to be specialized to make a lib support new types. Most users won't want to sip in them names when they say `using namespace thelib` so it's not public; it's not private either... I actually call this namespace ext
-- ___________________________________________ Joel Falcou - Assistant Professor PARALL Team - LRI - Universite Paris Sud XI Tel : (+33)1 69 15 66 35
joel wrote:
Jean-Louis Leroy wrote:
An example would be a namespace containing templates to be specialized to make a lib support new types. Most users won't want to sip in them names when they say `using namespace thelib` so it's not public; it's not private either...
I actually call this namespace ext
"extension" makes much more sense than "protected_." _____ Rob Stewart robert.stewart@sig.com Software Engineer, Core Software using std::disclaimer; Susquehanna International Group, LLP http://www.sig.com IMPORTANT: The information contained in this email and/or its attachments is confidential. If you are not the intended recipient, please notify the sender immediately by reply and immediately delete this message and all its attachments. Any review, use, reproduction, disclosure or dissemination of this message or any attachment by an unintended recipient is strictly prohibited. Neither this message nor any attachment is intended as or should be construed as an offer, solicitation or recommendation to buy or sell any security or other financial instrument. Neither the sender, his or her employer nor any of their respective affiliates makes any warranties as to the completeness or accuracy of any of the information contained herein or that this message or any of its attachments is free of viruses.
Jean-Louis Leroy wrote:
I actually call this namespace ext
`ext`...that's a good one...short and (subjectively ;-)) meaningful...I'll try it out for a while...
ext for extension or external or extra or extinct... for me it's completely ambiguous name. Now I've learned how the naming convention preferences are a subjective subject :-) Best regards, -- Mateusz Loskot, http://mateusz.loskot.net Charter Member of OSGeo, http://osgeo.org
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? Regards, -- Joel de Guzman http://www.boostpro.com http://spirit.sf.net http://www.facebook.com/djowel Meet me at BoostCon http://www.boostcon.com/home http://www.facebook.com/boostcon
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). Given that, namespace detail was judged as similarly not much informative as Impl and Base suffix. 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. I hope it clarifies the point. Best regards, -- Mateusz Loskot, http://mateusz.loskot.net
Hi, My opinions are made inline... On Tue, Oct 13, 2009 at 9:20 AM, Mateusz Loskot <mateusz@loskot.net> 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, http://mateusz.loskot.net
Regards, Neil Groves
Neil Groves wrote:
Hi,
My opinions are made inline...
On Tue, Oct 13, 2009 at 9:20 AM, Mateusz Loskot <mateusz@loskot.net> 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
Mateusz Loskot wrote:
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.
As has been noted, if a class is a private, implementation detail, then some naming convention for that purpose is useful. I've seen "IC" used as a prefix to mean "implementation class." I've seen "Impl" or "_impl" as a suffix for the same purpose. These names indicate that they are not for library client use, even if they happen to be visible.
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.
While I've never been comfortable with "detail" and greatly prefer "details," the point is that it is a namespace, nested within another, more meaningfully named namespace, that holds implementation details that should be ignored by those using the enclosing namespace. There's no need for a name with any more meaning than that in many cases. However, it is quite reasonable to nest other namespaces within detail(s) in order to segregate details, all related to the outer namespace, by purpose. That is, if there are too many unrelated implementation details in the foo::details namespace, then foo::details should be subdivided.
It raised some questions for myself, being interested in improving my craft, I would like to learn better about the name of namespace detail. I use detail name myself. Any better names for bucket with implementation details?
Any time there is value in grouping things by a categorical name, do so. However, when those are implementation details of something else that should be visible to clients, then those details should be in a namespace like "details" to set them apart. _____ Rob Stewart robert.stewart@sig.com Software Engineer, Core Software using std::disclaimer; Susquehanna International Group, LLP http://www.sig.com IMPORTANT: The information contained in this email and/or its attachments is confidential. If you are not the intended recipient, please notify the sender immediately by reply and immediately delete this message and all its attachments. Any review, use, reproduction, disclosure or dissemination of this message or any attachment by an unintended recipient is strictly prohibited. Neither this message nor any attachment is intended as or should be construed as an offer, solicitation or recommendation to buy or sell any security or other financial instrument. Neither the sender, his or her employer nor any of their respective affiliates makes any warranties as to the completeness or accuracy of any of the information contained herein or that this message or any of its attachments is free of viruses.
Stewart, Robert wrote:
Mateusz Loskot wrote:
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.
As has been noted, if a class is a private, implementation detail, then some naming convention for that purpose is useful. I've seen "IC" used as a prefix to mean "implementation class." I've seen "Impl" or "_impl" as a suffix for the same purpose. These names indicate that they are not for library client use, even if they happen to be visible.
Yes, I've seen exactly the same use if these. It looks _impl, _base, all these are conventions well settled in the C++ world. I don't mind using them myself.
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.
While I've never been comfortable with "detail" and greatly prefer "details," the point is that it is a namespace, nested within another, more meaningfully named namespace, that holds implementation details that should be ignored by those using the enclosing namespace. There's no need for a name with any more meaning than that in many cases.
Understood. I've been following the same and I'm comfortable with it, however during recent discussions made me asking myself if and where thing could be improved.
However, it is quite reasonable to nest other namespaces within detail(s) in order to segregate details, all related to the outer namespace, by purpose. That is, if there are too many unrelated implementation details in the foo::details namespace, then foo::details should be subdivided.
Yes, makes sense to me.
It raised some questions for myself, being interested in improving my craft, I would like to learn better about the name of namespace detail. I use detail name myself. Any better names for bucket with implementation details?
Any time there is value in grouping things by a categorical name, do so. However, when those are implementation details of something else that should be visible to clients, then those details should be in a namespace like "details" to set them apart.
Very well said. I'll take it as a rule and definition of how to use namespace details. Best regards, -- Mateusz Loskot, http://mateusz.loskot.net
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.
It raised some questions for myself, being interested in improving my craft, I would like to learn better about the name of namespace detail. I use detail name myself. Any better names for bucket with implementation details?
FWIW, I personally tend to use "aux", from "auxiliary". It is short enough, so it doesn't bloat symbol names too much, and it gives the idea that something internal is inside (especially, if the namespace is documented accordingly). IMO, all the naming-related arguments are highly subjective, and thus are unlikely to come to a common agreement. If you choose the name that is clear enough, documented and has the close meaning to the existing similar names out in the wild, then your choice is justified enough already. Speaking of Boost, the "detail" namespace is commonly used for implementation details, same as "aux" (or variations thereof), so this is a good choice if you're writing a new library for Boost.
Speaking of Boost, the "detail" namespace is commonly used for implementation details, same as "aux" (or variations thereof), so this is a good choice if you're writing a new library for Boost.
I may stick to the tradition (actually I'm doing that for now) but if we always limited ourselves to common usage, Boost would not exist to start with would it ? ;-) J-L
AMDG Jean-Louis Leroy wrote:
Speaking of Boost, the "detail" namespace is commonly used for implementation details, same as "aux" (or variations thereof), so this is a good choice if you're writing a new library for Boost.
I may stick to the tradition (actually I'm doing that for now) but if we always limited ourselves to common usage, Boost would not exist to start with would it ? ;-)
Sure, but there's not much point to innovating for irrelevant details. In Christ, Steven Watanabe
Jean-Louis Leroy wrote:
Speaking of Boost, the "detail" namespace is commonly used for implementation details, same as "aux" (or variations thereof), so this is a good choice if you're writing a new library for Boost.
I may stick to the tradition (actually I'm doing that for now) but if we always limited ourselves to common usage, Boost would not exist to start with would it ? ;-)
You don't mean that every library should reinvent the wheel, do you? There's nothing bad in following the common practice, it doesn't mean you're not moving forward.
Jean-Louis Leroy wrote:
Speaking of Boost, the "detail" namespace is commonly used for implementation details, same as "aux" (or variations thereof), so this is a good choice if you're writing a new library for Boost.
I may stick to the tradition (actually I'm doing that for now) but if we always limited ourselves to common usage, Boost would not exist to start with would it ? ;-)
J-L
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
I would suggest that consistency is more important in coding style issues than the actual constraint. Within Boost, detail has a well known meaning. I think it would be unwise to deviate from such style precedence unless there was a very compelling reason. michael -- ---------------------------------- Michael Caisse Object Modeling Designs www.objectmodelingdesigns.com
participants (10)
-
Andrey Semashev -
Jean-Louis Leroy -
joel -
Joel de Guzman -
Mateusz Loskot -
Michael Caisse -
Neil Groves -
Stefan Strasser -
Steven Watanabe -
Stewart, Robert