[iostreams] request for advice on naming [repost]
Dear all, I'm considering some last minute name changes for the iostreams library, and would like some feedback. There are two issues: 1. the names of the fundamental components streambuf_facade and stream_facade 2. inconsistent header names (Note: these changes shouldn't affect the regression tests -- unless I botch them) ----------------------- streambuf_facade and stream_facade: Before I settled on "streambuf_facade" and "stream_facade," I tried five or six other pairs of names for these templates. I finally picked the current names because of the analogy with the iterators library. However, the templates are not really facades -- in the GOF sense -- and I'm not sure that the analogy with the iterators library will be very effective in helping users understand these templates. As a result, I'm think of using the less technical-sounding names "generic_streambuf" and "generic_stream." What do people think? ----------------------- inconsistent header names: Until now I've followed the policy that a header should have the same name as the component it contains, if it contains a single component, and a short descriptive name if it contains several related components. For example, the header regex_filter.hpp contains the single component regex_filter, while the header zlib.hpp contains the component zlib_error, zlib_params, zlib_compressor and zlib_decompressor. This policy has resulted in a peculiar mix of names. For instance, boost/iostreams/filter now contains: bzip2.hpp counter.hpp gzip.hpp line_filter.hpp newline.hpp one_step_filter.hpp regex_filter.hpp stdio_filter.hpp symmetric_filter_adapter.hpp test.hpp zlib.hpp As you can see, some contain "_filter" and some don't, and it all depends on whether the header contains more than one component, which can be hard to remember. I'm thinking of renaming the headers that are curently based on component names so that all headers will have short, simple names. E.g., bzip2.hpp counter.hpp gzip.hpp line.hpp newline.hpp one_step.hpp regex.hpp stdio.hpp symmetric.hpp test.hpp zlib.hpp Thoughts? Best Regards, Jonathan
Jonathan Turkanis <technews <at> kangaroologic.com> writes:
sure that the analogy with the iterators library will be very effective in helping users understand these templates. As a result, I'm think of using the less technical-sounding names "generic_streambuf" and "generic_stream."
What do people think?
seems ok. have you considered basic_streambuf<> basic_stream<> as an analogy with regex/string etc ?
I'm thinking of renaming the headers that are curently based on component names so that all headers will have short, simple names. E.g.,
bzip2.hpp counter.hpp gzip.hpp line.hpp newline.hpp one_step.hpp regex.hpp stdio.hpp symmetric.hpp test.hpp zlib.hpp
Thoughts?
I like you renaming. -Thorsten
From: Thorsten Ottosen <nesotto@cs.aau.dk>
Jonathan Turkanis <technews <at> kangaroologic.com> writes:
sure that the analogy with the iterators library will be very effective in helping users understand these templates. As a result, I'm think of using the less technical-sounding names "generic_streambuf" and "generic_stream."
What do people think?
seems ok. have you considered
Hmmm. I agree that the original names are misleading. They don't create a facade over another class, they are provide the functionality directly. However, "generic_streambuf" sounds too, well, generic.
basic_streambuf<> basic_stream<>
as an analogy with regex/string etc ?
As compared to std::basic_istream et al, these classes are hardly what one would call basic. They push the concepts far forward. Thus, should these classes be standardized, std::basic_stream doesn't stand apart from the other class templates. Furthermore, they aren't specialized on the character type as those other templates are, so they deserve different names. Is there are reason not to call them simply "stream" and "streambuf?" If you're concerned about the possibility of typedefs or other uses of those names in either the std or boost namespace, then how about "policy_stream" and "policy_streambuf?"
I'm thinking of renaming the headers that are curently based on component names so that all headers will have short, simple names. E.g.,
bzip2.hpp counter.hpp gzip.hpp line.hpp newline.hpp one_step.hpp regex.hpp stdio.hpp symmetric.hpp test.hpp zlib.hpp
Thoughts?
I like you renaming.
Seems reasonable given that they are already in the filter subdirectory. -- Rob Stewart stewart@sig.com Software Engineer http://www.sig.com Susquehanna International Group, LLP using std::disclaimer;
Rob Stewart wrote:
From: Thorsten Ottosen <nesotto@cs.aau.dk>
Jonathan Turkanis <technews <at> kangaroologic.com> writes:
sure that the analogy with the iterators library will be very effective in helping users understand these templates. As a result, I'm think of using the less technical-sounding names "generic_streambuf" and "generic_stream."
What do people think?
seems ok. have you considered
Hmmm. I agree that the original names are misleading. They don't create a facade over another class, they are provide the functionality directly. However, "generic_streambuf" sounds too, well, generic.
Meaning the names are pretty dull? Thats true. I guess I could call them platinum_stream and platinum_streambuf ;-)
basic_streambuf<> basic_stream<>
as an analogy with regex/string etc ?
As compared to std::basic_istream et al, these classes are hardly what one would call basic. They push the concepts far forward. Thus, should these classes be standardized, std::basic_stream doesn't stand apart from the other class templates.
I agree. And basic_streambuf is already used by the standard. I'd rather not declare a type in a boost namespace with the same unqualified name as a type in namespace std, unless the type is recommended as a replacement for the standard type. For example, I define a template boost::iostreams::char_traits which is like std::char_traits except it supports would_block in addition to eof.
Furthermore, they aren't specialized on the character type as those other templates are, so they deserve different names.
Is there are reason not to call them simply "stream" and "streambuf?"
I like these, except that streambuf is a typedef in namespace std for basic_streambuf<char>.
If you're concerned about the possibility of typedefs or other uses of those names in either the std or boost namespace, then how about "policy_stream" and "policy_streambuf?"
These are very good, but I've tenatively decided to downplay the policy-based aspect of the design. I know at least one person who was turned off by the description of the library as involving policies. While I disagree with his view, and I hope he is not representive of users in general, his reaction made me realize that calling the library policy-based doesn't really add much. Still, I like these names, and will think about using them.
I'm thinking of renaming the headers that are curently based on component names so that all headers will have short, simple names. E.g.,
bzip2.hpp counter.hpp gzip.hpp line.hpp newline.hpp one_step.hpp regex.hpp stdio.hpp symmetric.hpp test.hpp zlib.hpp
Thoughts?
I like you renaming.
Seems reasonable given that they are already in the filter subdirectory.
Okay, thanks. Jonathan
From: "Jonathan Turkanis" <technews@kangaroologic.com>
Rob Stewart wrote:
From: Thorsten Ottosen <nesotto@cs.aau.dk>
Jonathan Turkanis <technews <at> kangaroologic.com> writes:
Hmmm. I agree that the original names are misleading. They don't create a facade over another class, they are provide the functionality directly. However, "generic_streambuf" sounds too, well, generic.
Meaning the names are pretty dull? Thats true. I guess I could call them platinum_stream and platinum_streambuf ;-)
:0) I didn't mean dull so much as redundant or even useless (as in not providing any benefit).
Is there are reason not to call them simply "stream" and "streambuf?"
I like these, except that streambuf is a typedef in namespace std for basic_streambuf<char>.
Yeah, that would be a problem if they were standardized, but there are likely to be a number of changes should they be standardized, that I'm not sure this is worth worrying about. OTOH, your concern about duplicating a name from the standard library that isn't intended as a replacement is well-founded.
If you're concerned about the possibility of typedefs or other uses of those names in either the std or boost namespace, then how about "policy_stream" and "policy_streambuf?"
These are very good, but I've tenatively decided to downplay the policy-based aspect of the design. I know at least one person who was turned off by the description of the library as involving policies. While I disagree with his view, and I hope he is not representive of users in general, his reaction made me realize that calling the library policy-based doesn't really add much.
A reasonable position, that.
Still, I like these names, and will think about using them.
You may find these a bit redundant, but what about "iostream" and "iostreambuf?" Another approach, which I like less, but might give you an idea, is "streamer" and "streambuffer." (Well, "streambuffer" is just fine, but I don't care much for "streamer.") Maybe a departure from "stream" is in order: pipe, pipeline, formatter, ...? -- Rob Stewart stewart@sig.com Software Engineer http://www.sig.com Susquehanna International Group, LLP using std::disclaimer;
Rob Stewart wrote:
From: "Jonathan Turkanis" <technews@kangaroologic.com>
Rob Stewart wrote:
From: Thorsten Ottosen <nesotto@cs.aau.dk>
Jonathan Turkanis <technews <at> kangaroologic.com> writes:
Hmmm. I agree that the original names are misleading. They don't create a facade over another class, they are provide the functionality directly. However, "generic_streambuf" sounds too, well, generic.
Meaning the names are pretty dull? Thats true. I guess I could call them platinum_stream and platinum_streambuf ;-)
0)
I didn't mean dull so much as redundant or even useless (as in not providing any benefit).
Okay.
Is there are reason not to call them simply "stream" and "streambuf?"
I like these, except that streambuf is a typedef in namespace std for basic_streambuf<char>.
Yeah, that would be a problem if they were standardized, but there are likely to be a number of changes should they be standardized, that I'm not sure this is worth worrying about.
OTOH, your concern about duplicating a name from the standard library that isn't intended as a replacement is well-founded.
Still, I like these names, and will think about using them.
You may find these a bit redundant, but what about "iostream" and "iostreambuf?"
'iostream' suffers the same problem as 'streambuf': it already names a type in namespace std.
Another approach, which I like less, but might give you an idea, is "streamer" and "streambuffer." (Well, "streambuffer" is just fine, but I don't care much for "streamer.")
I think I need to keep stream and streambuf as components of the names, because I don't want to rename filtering_stream/filtering_streambuf.
Maybe a departure from "stream" is in order: pipe, pipeline, formatter, ...?
'pipeline' is already used for the return type of expressions like gzip_compressor() | base64_encoder() | file_sink(...) I may use the name 'pipe' for wrappers for operating system pipes, or portable replacements. 'formatter' seems in appropriate, since for now the library handles only unformatted i/o, relying on the standard iostreams library to provide a formatting layer. Maybe I could go Alexandrescuesque: flex_stream, flex_streambuf Or black separatist: xstream, xstreambuf Actually, this looks pretty good. Maybe it would run afoul of the prohibition against cryptic names; there's a precedent, however, in xtime from Boost.Threads. Jonathan
From: "Jonathan Turkanis" <technews@kangaroologic.com>
Rob Stewart wrote:
From: "Jonathan Turkanis" <technews@kangaroologic.com>
Rob Stewart wrote:
From: Thorsten Ottosen <nesotto@cs.aau.dk>
Jonathan Turkanis <technews <at> kangaroologic.com> writes:
You may find these a bit redundant, but what about "iostream" and "iostreambuf?"
'iostream' suffers the same problem as 'streambuf': it already names a type in namespace std.
Right. Same problem/same opportunity to ignore until standardization.
Another approach, which I like less, but might give you an idea, is "streamer" and "streambuffer." (Well, "streambuffer" is just fine, but I don't care much for "streamer.")
I think I need to keep stream and streambuf as components of the names, because I don't want to rename filtering_stream/filtering_streambuf.
Well, whatever you call generic_stream and generic_streambuf, can't filtering_stream and filtering_streambuf follow suit?
Maybe a departure from "stream" is in order: pipe, pipeline, formatter, ...?
'pipeline' is already used for the return type of expressions like
gzip_compressor() | base64_encoder() | file_sink(...)
Yeah, I was just trying to find something that might work or trigger a thought in your head.
I may use the name 'pipe' for wrappers for operating system pipes, or portable
Sure.
replacements. 'formatter' seems in appropriate, since for now the library handles only unformatted i/o, relying on the standard iostreams library to provide a formatting layer.
Agreed.
Maybe I could go Alexandrescuesque:
flex_stream, flex_streambuf
Well, due to the PBD, they are flexible.
Or black separatist:
xstream, xstreambuf
Actually, this looks pretty good. Maybe it would run afoul of the prohibition against cryptic names; there's a precedent, however, in xtime from Boost.Threads.
The "x" can imply "extension" or "extended," so that does work pretty nicely. Besides, it keeps the names short. -- Rob Stewart stewart@sig.com Software Engineer http://www.sig.com Susquehanna International Group, LLP using std::disclaimer;
Rob Stewart wrote:
From: "Jonathan Turkanis"
Rob Stewart wrote:
You may find these a bit redundant, but what about "iostream" and "iostreambuf?"
'iostream' suffers the same problem as 'streambuf': it already names a type in namespace std.
Right. Same problem/same opportunity to ignore until standardization.
If I choose to ignore the problem, I prefer 'stream' and 'streambuf.'
Another approach, which I like less, but might give you an idea, is "streamer" and "streambuffer." (Well, "streambuffer" is just fine, but I don't care much for "streamer.")
I think I need to keep stream and streambuf as components of the names, because I don't want to rename filtering_stream/filtering_streambuf.
Well, whatever you call generic_stream and generic_streambuf, can't filtering_stream and filtering_streambuf follow suit?
Yes, but I like the names filtering_stream and filtering_streambuf. Among other things, they're close to James Kanze's original names.
Maybe a departure from "stream" is in order: pipe, pipeline, formatter, ...?
'pipeline' is already used for the return type of expressions like
gzip_compressor() | base64_encoder() | file_sink(...)
Yeah, I was just trying to find something that might work or trigger a thought in your head.
Okay. Unfortunately it hasn't happened yet ;-)
I may use the name 'pipe' for wrappers for operating system pipes, or portable
Sure.
replacements. 'formatter' seems in appropriate, since for now the library handles only unformatted i/o, relying on the standard iostreams library to provide a formatting layer.
Agreed.
Maybe I could go Alexandrescuesque:
flex_stream, flex_streambuf
Well, due to the PBD, they are flexible.
Or black separatist:
xstream, xstreambuf
Actually, this looks pretty good. Maybe it would run afoul of the prohibition against cryptic names; there's a precedent, however, in xtime from Boost.Threads.
The "x" can imply "extension" or "extended," so that does work pretty nicely. Besides, it keeps the names short.
I think I like these. I had another idea: device_stream, device_streambuf Unlike 'stream_facade' and 'streambuf_facade,' these are perfect descriptions of the components. They don't roll off the tongue very easily, though. Jonathan
From: "Jonathan Turkanis" <technews@kangaroologic.com>
I had another idea:
device_stream, device_streambuf
Unlike 'stream_facade' and 'streambuf_facade,' these are perfect descriptions of the components. They don't roll off the tongue very easily, though.
"device_stream" suggests a stream of devices rather than of data. Besides, I don't really get the reference to "device." That does lead me to suggest "data_stream" and "data_streambuf," however. -- Rob Stewart stewart@sig.com Software Engineer http://www.sig.com Susquehanna International Group, LLP using std::disclaimer;
Rob Stewart wrote:
From: "Jonathan Turkanis" <technews@kangaroologic.com>
I had another idea:
device_stream, device_streambuf
Unlike 'stream_facade' and 'streambuf_facade,' these are perfect descriptions of the components. They don't roll off the tongue very easily, though.
"device_stream" suggests a stream of devices rather than of data. Besides, I don't really get the reference to "device."
That does lead me to suggest "data_stream" and "data_streambuf," however.
Oddly, the library from which these components originally came was called Datastreams. "data_stream" and "data_streambuf" have the same problem as "generic_stream" and "generic_streambuf": the prefix "data_" doesn't add any information, since all streams and stream buffers process data in one form or another. In fact, I think they're slightly worse than "generic_stream" and "generic_streambuf," because someone might think that "data" has a special meaning in this context, when in fact it doesn't. I think I've narrowed it down to "xxx_facade," "device_xxx," "devxxx" (suggested by Gareth Sylvester-Bradley) and "xxxx" (note the extra 'x' ;-) ). I'm going to try to get more people involved by soliciting votes. People seem to like voting, for some reason. Thanks for brainstorming with me. Jonathan
Thorsten Ottosen wrote:
Jonathan Turkanis <technews <at> kangaroologic.com> writes:
sure that the analogy with the iterators library will be very effective in helping users understand these templates. As a result, I'm think of using the less technical-sounding names "generic_streambuf" and "generic_stream."
What do people think?
seems ok. have you considered
basic_streambuf<>
This one is taken ;-)
basic_stream<>
as an analogy with regex/string etc ?
I'm thinking of renaming the headers that are curently based on component names so that all headers will have short, simple names. E.g.,
bzip2.hpp counter.hpp gzip.hpp line.hpp newline.hpp one_step.hpp regex.hpp stdio.hpp symmetric.hpp test.hpp zlib.hpp
Thoughts?
I like you renaming.
Okay, thanks.
-Thorsten
Jonathan
On 07/07/2005 11:50 PM, Jonathan Turkanis wrote: [snip]
inconsistent header names: [snip] As you can see, some contain "_filter" and some don't, and it all depends on whether the header contains more than one component, which can be hard to remember.
It would be nice if a header file name could end in "_+.hpp" where the "+" is meant to suggest "more than one component". Maybe just "_" would be close enough, so that a header named: counter_.hpp would indicate it contains components with names starting with "counter_" or components having something to do with a counter. Is that any better?
Larry Evans wrote:
On 07/07/2005 11:50 PM, Jonathan Turkanis wrote: [snip]
inconsistent header names: [snip] As you can see, some contain "_filter" and some don't, and it all depends on whether the header contains more than one component, which can be hard to remember.
It would be nice if a header file name could end in "_+.hpp" where the "+" is meant to suggest "more than one component".
I think some filesystems don't allow + in file names; that's why c++boost.gif was renamed.
Maybe just "_" would be close enough, so that a header named:
counter_.hpp
would indicate it contains components with names starting with "counter_" or components having something to do with a counter.
Is that any better?
I generally try to avoid trailling underscores, since they look funny to me. Also, I'm not sure that when a header contains more than one component, their names only differ at the end. Using a trailing _ also forces people to remember whether a header contains more than one component, which is something I wanted to avoid. For example, newline.hpp contains newline_filter and newline_checker. My guess is that newline_filter will be used much more frequently, and some people may not even relaize that there is another filter defined in the same header. Jonathan
From: Larry Evans <cppljevans@cox-internet.com>
It would be nice if a header file name could end in "_+.hpp" where the "+" is meant to suggest "more than one component". Maybe just "_" would be close enough, so that a header named:
counter_.hpp
would indicate it contains components with names starting with "counter_" or components having something to do with a counter.
What would you name the header for class static_? I don't see a trailing underscore, which is a valid character in an identifier, as a good wildcard character. -- Rob Stewart stewart@sig.com Software Engineer http://www.sig.com Susquehanna International Group, LLP using std::disclaimer;
On 07/08/2005 12:56 PM, Rob Stewart wrote:
From: Larry Evans <cppljevans@cox-internet.com> [snip] What would you name the header for class static_?
I don't see a trailing underscore, which is a valid character in an identifier, as a good wildcard character.
What would you name the header for class static? Obviously you'd have to constrain your class names to conform to the convention that there's no static_, just as in Jonathan's proposed naming convention there would be no name static, IIUC.
From: Larry Evans <cppljevans@cox-internet.com>
On 07/08/2005 12:56 PM, Rob Stewart wrote:
From: Larry Evans <cppljevans@cox-internet.com> [snip] What would you name the header for class static_?
I don't see a trailing underscore, which is a valid character in an identifier, as a good wildcard character.
What would you name the header for class static? Obviously you'd have to constrain your class names to conform to the convention that there's no static_, just as in Jonathan's proposed naming convention there would be no name static, IIUC.
I understood you to propose a naming convention that could well apply beyond Boost.IOStreams. class static_ might model static in an electronics simulation. My point was that there are class names one might choose that correspond to keywords, so one may choose to use an underscore in such a class name to avoid the keyword. A file for such a class would have a filename that reflects the class name, thus ending with an underscore. If you're saying you'd disallow such class names, I suppose that may work, but it is limiting. -- Rob Stewart stewart@sig.com Software Engineer http://www.sig.com Susquehanna International Group, LLP using std::disclaimer;
Rob Stewart wrote:
From: Larry Evans <cppljevans@cox-internet.com>
It would be nice if a header file name could end in "_+.hpp" where the "+" is meant to suggest "more than one component". Maybe just "_" would be close enough, so that a header named:
counter_.hpp
would indicate it contains components with names starting with "counter_" or components having something to do with a counter.
What would you name the header for class static_?
I don't see a trailing underscore, which is a valid character in an identifier, as a good wildcard character.
I guess you could use counter_xxx, static_xxx. I simply don't like the idea of wildcards in header names. Jonathan
participants (4)
-
Jonathan Turkanis -
Larry Evans -
Rob Stewart -
Thorsten Ottosen