I was just looking at using Boost.Range in my new Sequence library and noticed the following: 1. The documentation of requirements uses names like range_iterator without qualification. You need to add the boost:: prefix or make it very clear that all names are implicitly boost:: prefixed (as opposed to, say, boost::range:: prefixed). I prefer the former; people may land on the documentation for reference without reading all the introductory material. 2. Names like range_iterator in the requirements tables should be hyperlinked to some documentation for them. 3. The documentation you land on should clearly state in which header those names can be found. 4. Having a pile of names prefixed by "range_" (like boost::range_const_iterator) just seems wrong to me when we have namespaces. Is there a good reason we're not using boost::range::const_iterator or boost::ranges::const_iterator? -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams wrote:
I was just looking at using Boost.Range in my new Sequence library and noticed the following:
4. Having a pile of names prefixed by "range_" (like boost::range_const_iterator) just seems wrong to me when we have namespaces. Is there a good reason we're not using boost::range::const_iterator or boost::ranges::const_iterator?
I think I'm partially responsible for this. Originally Thorsten was using the names value_type_of, difference_of, iterator_of, etc, and I pointed out that the iterator library uses the names iterator_xxx for similar metafunctions. I believe there was extensive discussion about it at the time. Jonathan
"Jonathan Turkanis" <technews@kangaroologic.com> writes:
David Abrahams wrote:
I was just looking at using Boost.Range in my new Sequence library and noticed the following:
4. Having a pile of names prefixed by "range_" (like boost::range_const_iterator) just seems wrong to me when we have namespaces. Is there a good reason we're not using boost::range::const_iterator or boost::ranges::const_iterator?
I think I'm partially responsible for this. Originally Thorsten was using the names value_type_of, difference_of, iterator_of, etc, and I pointed out that the iterator library uses the names iterator_xxx for similar metafunctions. I believe there was extensive discussion about it at the time.
Two wrongs don't make a right! Mea culpa; I should have put those in boost::iterators::. -- Dave Abrahams Boost Consulting www.boost-consulting.com
"David Abrahams" <dave@boost-consulting.com> wrote in message news:uekcpcfg2.fsf@boost-consulting.com... | | I was just looking at using Boost.Range in my new Sequence library and | noticed the following: | | 1. The documentation of requirements uses names like range_iterator | without qualification. You need to add the boost:: prefix or | make it very clear that all names are implicitly boost:: prefixed | (as opposed to, say, boost::range:: prefixed). I prefer the | former; people may land on the documentation for reference | without reading all the introductory material. | | 2. Names like range_iterator in the requirements tables should be | hyperlinked to some documentation for them. yeah, good idea. | 3. The documentation you land on should clearly state in which | header those names can be found. there is a header section. | 4. Having a pile of names prefixed by "range_" (like | boost::range_const_iterator) just seems wrong to me when we have | namespaces. Is there a good reason we're not using | boost::range::const_iterator or boost::ranges::const_iterator? decision made in review or post-review. people like it that way. -Thorsten
"Thorsten Ottosen" <nesotto@cs.auc.dk> writes:
"David Abrahams" <dave@boost-consulting.com> wrote in message news:uekcpcfg2.fsf@boost-consulting.com... | | I was just looking at using Boost.Range in my new Sequence library and | noticed the following: | | 1. The documentation of requirements uses names like range_iterator | without qualification. You need to add the boost:: prefix or | make it very clear that all names are implicitly boost:: prefixed | (as opposed to, say, boost::range:: prefixed). I prefer the | former; people may land on the documentation for reference | without reading all the introductory material. | | 2. Names like range_iterator in the requirements tables should be | hyperlinked to some documentation for them.
yeah, good idea.
| 3. The documentation you land on should clearly state in which | header those names can be found.
there is a header section.
I know that. But when you land on the documentation for range_value (for example) the header it's in should be visible.
| 4. Having a pile of names prefixed by "range_" (like | boost::range_const_iterator) just seems wrong to me when we have | namespaces. Is there a good reason we're not using | boost::range::const_iterator or boost::ranges::const_iterator?
decision made in review or post-review. people like it that way.
Count one more vote against, FWIW. -- Dave Abrahams Boost Consulting www.boost-consulting.com
| 4. Having a pile of names prefixed by "range_" (like | > | boost::range_const_iterator) just seems wrong to me when we have | > | namespaces. Is there a good reason we're not using | > | boost::range::const_iterator or boost::ranges::const_iterator? | > | > decision made in review or post-review. people like it that way. | | Count one more vote against, FWIW.
ok, will do. the question that I have is that will changing these names have any effect except on me which has to do it? if we can provide more thourough naming guide-lines for future boost libs, then let's do so. -Thorsten
Thorsten Ottosen wrote:
4. Having a pile of names prefixed by "range_" (like
boost::range_const_iterator) just seems wrong to me when we have namespaces. Is there a good reason we're not using boost::range::const_iterator or boost::ranges::const_iterator?
decision made in review or post-review. people like it that way.
Count one more vote against, FWIW.
ok, will do. the question that I have is that will changing these names have any effect except on me which has to do it?
if we can provide more thourough naming guide-lines for future boost libs, then let's do so.
This affects me too. In the iostreams library I had metafunctions named category and char_type which in the usual case simply extract member types of the same name. In the interest of uniform naming I changed these to io_category and io_char, which sound a bit funny to me, esp. the latter. Jonathan
"Jonathan Turkanis" <technews@kangaroologic.com> wrote in message news:d589ja$cp2$1@sea.gmane.org... | Thorsten Ottosen wrote: | >>> 4. Having a pile of names prefixed by "range_" (like | >>>> boost::range_const_iterator) just seems wrong to me when we | >>>> have namespaces. Is there a good reason we're not using | >>>> boost::range::const_iterator or boost::ranges::const_iterator? | >>> | >>> decision made in review or post-review. people like it that way. | >> | >> Count one more vote against, FWIW. | > | > | > ok, will do. the question that I have is that will changing these | > names have any effect except on me which has to do it? | > | > if we can provide more thourough naming guide-lines for future boost | > libs, then let's do so. | | This affects me too. In the iostreams library I had metafunctions named category | and char_type which in the usual case simply extract member types of the same | name. In the interest of uniform naming I changed these to io_category and | io_char, which sound a bit funny to me, esp. the latter. well, you can't call it io::char :-) -Thorsten
"Jonathan Turkanis" <technews@kangaroologic.com> wrote in message news:d58c5t$lbl$1@sea.gmane.org... | Thorsten Ottosen wrote: | | > well, you can't call it io::char :-) | | Yeah, I know. Since char_<> would be an abomination, the alternative is | char_type. I've got the same problem with int_type. one could of course say io::character io::integer -Thorsten
Thorsten Ottosen wrote:
"Jonathan Turkanis" <technews@kangaroologic.com> wrote in message news:d58c5t$lbl$1@sea.gmane.org...
Thorsten Ottosen wrote:
well, you can't call it io::char :-)
Yeah, I know. Since char_<> would be an abomination, the alternative is char_type. I've got the same problem with int_type.
one could of course say
io::character io::integer
Not bad! Thanks. I wonder if the nested type should be called character as well. I've taken it for granted that I should use the standard library convention, but maybe that's not so important: struct my_filter { typedef char character; typedef input_filter_tag category; ... }; Jonathan
"Jonathan Turkanis" <technews@kangaroologic.com> writes:
Thorsten Ottosen wrote:
well, you can't call it io::char :-)
Yeah, I know. Since char_<> would be an abomination,
Why?
the alternative is char_type.
character_type?
I've got the same problem with int_type.
Not sure how that fits in... :( -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams wrote:
"Jonathan Turkanis" <technews@kangaroologic.com> writes:
Thorsten Ottosen wrote:
well, you can't call it io::char :-)
Yeah, I know. Since char_<> would be an abomination,
Why?
Other things being equal, I like to avoid trailing underscores except for member names, since they look wierd to me.I respect the use of int_, long_, ... in mpl because they name entities closely tied to the keywords, so it makes sense to choose the closest legal alternatives. In Iostreams, the connection between the keyword char and the metafunction which extracts the character type of a device is more remote. I'd rather have a desciptive name.
the alternative is char_type.
character_type?
character_type and char_type both suffer from the problem that they look funny when they are applied typename char_type<Device>::type // 'type' is repeated But we discussed this already some time ago.
I've got the same problem with int_type.
Not sure how that fits in... :(
Because I can't have a metafunction called int. Jonathan
participants (3)
-
David Abrahams -
Jonathan Turkanis -
Thorsten Ottosen