To name, perchance pleasingly

[Daniel]

I've been skimming the boost include directory for inspiration for naming subdirectories, namespaces, and class names, when the most natural name would be the same. As in boost, assume all lower case naming convention, so no help from mixed case differentiation.

Some examples from boost:

subdirectory name: bimap
namespace name: bimaps
class name: bimap

subdirectory name: iterator
namespace name: iterators
class name: iterator

subdirectory name: function_types
namespace name: function_types
class name: function_type

subdirectory name: optional
namespace name: optional_ns
class name: optional

Any thoughts? My immediate context is where the most natural name for a subdirectory, namespace and class name is "cbor" (a class encapsulating the Concise Binary Object Representation and related algorithms.)

Thanks,
Daniel

[Jorgen Grahn]

Post by Daniel
I've been skimming the boost include directory for inspiration for
naming subdirectories, namespaces, and class names, when the most
natural name would be the same. As in boost, assume all lower case
naming convention, so no help from mixed case differentiation.
subdirectory name: bimap
namespace name: bimaps
class name: bimap
subdirectory name: iterator
namespace name: iterators
class name: iterator
subdirectory name: function_types
namespace name: function_types
class name: function_type
subdirectory name: optional
namespace name: optional_ns
class name: optional

Note that Boost is a general library; different needs compared to a
class in a program.

Post by Daniel
Any thoughts? My immediate context is where the most natural name
for a subdirectory, namespace and class name is "cbor" (a class
encapsulating the Concise Binary Object Representation and related
algorithms.)

Having a 1:1 mapping between subdirectories and major namespaces
sounds like a good idea.

My only thought is that having both a namespace and a class named cbor
seems a bit suspect. Maybe the namespace isn't needed? Or maybe
there's a better class name? I'm not familiar with CBOR, but I could
imagine cbor::Encoder and cbor::Decoder being better names.

The class name should IMHO be read as in the context of the namespace,
and then cbor::cbor would just be superfluous, and say nothing about
the class itself.

/Jorgen

[Daniel]

Post by Jorgen Grahn

Post by Daniel
I've been skimming the boost include directory for inspiration for
naming subdirectories, namespaces, and class names, when the most
natural name would be the same. As in boost, assume all lower case
naming convention, so no help from mixed case differentiation.
subdirectory name: bimap
namespace name: bimaps
class name: bimap
subdirectory name: iterator
namespace name: iterators
class name: iterator
subdirectory name: function_types
namespace name: function_types
class name: function_type
subdirectory name: optional
namespace name: optional_ns
class name: optional

Note that Boost is a general library; different needs compared to a
class in a program.

The context is a general purpose open source library for json, cbor,
msgpack and related json-inspired data models, as well as standard and defacto standard algorithms that apply to these data models, such as
jsonpath, json content rules, jsonpointer, and jsonpatch. So the needs are
the same.

Post by Jorgen Grahn

Post by Daniel
Any thoughts? My immediate context is where the most natural name
for a subdirectory, namespace and class name is "cbor" (a class
encapsulating the Concise Binary Object Representation and related
algorithms.)

Having a 1:1 mapping between subdirectories and major namespaces
sounds like a good idea.

Agreed. That's what boost does most of the time, except in the few cases
where the "natural" name for the subdirectory, path and class are the same,
e.g. bimap. In that case boost made the namespace plural, but in the case
of option, they made the namespace option_ns.

Post by Jorgen Grahn
My only thought is that having both a namespace and a class named cbor
seems a bit suspect. Maybe the namespace isn't needed?

It is. cbor, msgpack, jsonpointer, jsonpath etc. are distinct libraries.

Post by Jorgen Grahn
Or maybe
there's a better class name? I'm not familiar with CBOR, but I could
imagine cbor::Encoder and cbor::Decoder being better names.

Encoders, decoders, validators, there are all of those things, but
in addition there's a need for a value representation of the bytes,
with a corresponding set of member functions, some common to json,
cbor, and msgpack. That's what allows query algorithms like jsonpointer
and jsonpath to be applied to any of the json-like data models,
whether unpacked or binary encoded.

But this is the main issue, whether to choose a different namespace
name, which seems to be boost's practice, or to give the value like class a
different name, e.g. cbor_val or cbor_value.

Post by Jorgen Grahn
The class name should IMHO be read as in the context of the namespace,
and then cbor::cbor would just be superfluous, and say nothing about
the class itself.

I suppose cbor::value (msgpack::value) would be an option, but value by
itself seems uninspired. Or perhaps cbor::packed (msgpack::packed), as
these encapsulate packed arrays of bytes.

Thanks for the comments, questions about naming conventions tend to be sparsely responded to here :-) But at the same, there are clearly best practices for naming, and with libraries it's helpful to follow conventions,
so feedback appreciated.

Daniel

[Jorgen Grahn]

...

Post by Daniel

Post by Jorgen Grahn
Or maybe
there's a better class name? I'm not familiar with CBOR, but I could
imagine cbor::Encoder and cbor::Decoder being better names.

Encoders, decoders, validators, there are all of those things, but
in addition there's a need for a value representation of the bytes,
with a corresponding set of member functions, some common to json,
cbor, and msgpack. That's what allows query algorithms like jsonpointer
and jsonpath to be applied to any of the json-like data models,
whether unpacked or binary encoded.
But this is the main issue, whether to choose a different namespace
name, which seems to be boost's practice, or to give the value like class a
different name, e.g. cbor_val or cbor_value.

Post by Jorgen Grahn
The class name should IMHO be read as in the context of the namespace,
and then cbor::cbor would just be superfluous, and say nothing about
the class itself.

I suppose cbor::value (msgpack::value) would be an option, but value by
itself seems uninspired.

cbor::value feels much better to me (except I might wonder how
"refined" this value is). If you keep the context (cbor) in mind,
it reads as "the kind of value that CBOR operates on".

To me the name is more demystifying and unsurprising than uninspired.

Post by Daniel
Or perhaps cbor::packed (msgpack::packed), as
these encapsulate packed arrays of bytes.

Yes, if the packedness is important to the user. Not if he doesn't
care if the value is unpacked when accessed, or unpacked when
retrieved.

Post by Daniel
Thanks for the comments, questions about naming conventions tend to
be sparsely responded to here :-) But at the same, there are clearly
best practices for naming, and with libraries it's helpful to follow
conventions, so feedback appreciated.

/Jorgen

[Tim Rentsch]

Post by Daniel

Post by Daniel
I've been skimming the boost include directory for inspiration for
naming subdirectories, namespaces, and class names, when the most
natural name would be the same. As in boost, assume all lower case
naming convention, so no help from mixed case differentiation.
subdirectory name: bimap
namespace name: bimaps
class name: bimap
subdirectory name: iterator
namespace name: iterators
class name: iterator
subdirectory name: function_types
namespace name: function_types
class name: function_type
subdirectory name: optional
namespace name: optional_ns
class name: optional

Note that Boost is a general library; different needs compared to a
class in a program.

The context is a general purpose open source library for json, cbor,
msgpack and related json-inspired data models, as well as standard
and defacto standard algorithms that apply to these data models, such
as
jsonpath, json content rules, jsonpointer, and jsonpatch. So the needs are
the same.

Post by Daniel
Any thoughts? My immediate context is where the most natural name
for a subdirectory, namespace and class name is "cbor" (a class
encapsulating the Concise Binary Object Representation and related
algorithms.)

Having a 1:1 mapping between subdirectories and major namespaces
sounds like a good idea.

Agreed. That's what boost does most of the time, except in the few cases
where the "natural" name for the subdirectory, path and class are the same,
e.g. bimap. In that case boost made the namespace plural, but in the case
of option, they made the namespace option_ns.

My only thought is that having both a namespace and a class named cbor
seems a bit suspect. Maybe the namespace isn't needed?

It is. cbor, msgpack, jsonpointer, jsonpath etc. are distinct libraries.

Or maybe
there's a better class name? I'm not familiar with CBOR, but I could
imagine cbor::Encoder and cbor::Decoder being better names.

Encoders, decoders, validators, there are all of those things, but
in addition there's a need for a value representation of the bytes,
with a corresponding set of member functions, some common to json,
cbor, and msgpack. That's what allows query algorithms like jsonpointer
and jsonpath to be applied to any of the json-like data models,
whether unpacked or binary encoded.
But this is the main issue, whether to choose a different namespace
name, which seems to be boost's practice, or to give the value like class a
different name, e.g. cbor_val or cbor_value.

The class name should IMHO be read as in the context of the namespace,
and then cbor::cbor would just be superfluous, and say nothing about
the class itself.

I suppose cbor::value (msgpack::value) would be an option, but value by
itself seems uninspired. Or perhaps cbor::packed (msgpack::packed), as
these encapsulate packed arrays of bytes.

I've kept all the context so as not to have to decide what to cut.

I think 'cbor' is a good choice for the name of the namespace (in
case it needs saying, given the context with parallel namespaces
such as msgpack, etc).

I think 'value' is a poor choice for a class name. It doesn't
say anything, kind of like 'cbor::thing'. The name 'packed' is
at least more descriptive than 'value', but still IMO a poor
choice.

If I were charged with proposing a name (and following the rule
of no uppercase letters), I think my first suggestion would be
'encoded_item'. (Needless to say that assumes that an instance
of the class does indeed hold an encoded item.) My rationale
is this name leaves no doubt in the reader's mind what an
instance of this class represents. It doesn't require any
guessing, imagination, or outside context, to undrstand what
is meant.

Does that all make sense?

[Daniel]

Post by Tim Rentsch
I think 'cbor' is a good choice for the name of the namespace (in
case it needs saying, given the context with parallel namespaces
such as msgpack, etc).
I think 'value' is a poor choice for a class name. It doesn't
say anything, kind of like 'cbor::thing'. The name 'packed' is
at least more descriptive than 'value', but still IMO a poor
choice.
If I were charged with proposing a name (and following the rule
of no uppercase letters), I think my first suggestion would be
'encoded_item'. (Needless to say that assumes that an instance
of the class does indeed hold an encoded item.) My rationale
is this name leaves no doubt in the reader's mind what an
instance of this class represents. It doesn't require any
guessing, imagination, or outside context, to undrstand what
is meant.
Does that all make sense?

Thanks for your comments and suggestions. I think all the comments agreed
that the namespace name should be cbor (singular).

For class name, 'encoded_item' could work, but I'm also inclined to a little
repetition as suggested in Richard's post and include "cbor" in the class
name. I agree with your comments about value as a class name.

I tentatively went with boost's approach for tuple, iterator, and bimap
(subdirectory singular, namespace plural, class name singular), hence cbor
(subdirectory), cbors (namespace) and cbor (class name). But I'm not
enthusiastic about it (partly from reflecting on comments on this thread)
and am thinking of changing it to cbor, cbor, and packed_cbor.

Daniel

[Tim Rentsch]

Post by Tim Rentsch
I think 'cbor' is a good choice for the name of the namespace (in
case it needs saying, given the context with parallel namespaces
such as msgpack, etc).
I think 'value' is a poor choice for a class name. It doesn't
say anything, kind of like 'cbor::thing'. The name 'packed' is
at least more descriptive than 'value', but still IMO a poor
choice.
If I were charged with proposing a name (and following the rule
of no uppercase letters), I think my first suggestion would be
'encoded_item'. (Needless to say that assumes that an instance
of the class does indeed hold an encoded item.) My rationale
is this name leaves no doubt in the reader's mind what an
instance of this class represents. It doesn't require any
guessing, imagination, or outside context, to undrstand what
is meant.
Does that all make sense?

Thanks for your comments and suggestions. I think all the comments
agreed that the namespace name should be cbor (singular).

Yes, unless there is some context I'm missing, cbor seems like
the most natural name for this namespace, or at least one of the
most natural, in terms of what it conveys to readers.

For class name, 'encoded_item' could work, but I'm also inclined to
a little repetition as suggested in Richard's post and include
"cbor" in the class name. I agree with your comments about value as
a class name.

I don't know how important the repetition is but it strikes me as
a reasonable choice here.

I tentatively went with boost's approach for tuple, iterator, and
bimap (subdirectory singular, namespace plural, class name
singular), hence cbor (subdirectory), cbors (namespace) and cbor
(class name). But I'm not enthusiastic about it (partly from
reflecting on comments on this thread)

I don't like the boost naming scheme. I understand it, and I
think I understand some of the motivations behind it, but it
grates on my low-level linguistic mental machinery, and that is
almost always a sign that somewhere a poor choice was made.

and am thinking of changing it to cbor, cbor, and packed_cbor.

Depending on what "packed" is supposed to mean, "packed_cbor" is
either pointlessly redundant or self-contradictory. Also, using
"cbor" as the main noun is wrong: CBOR is a scheme for encoding
something, not the resulting encoding. For what I think you want
this class to represent, "cbor" should be used as an adjective,
not a noun. So either "cbor_encoded_item" or "cbor_packed_item"
would be a better choice for the class name. Yes, the name is a
little long, but it is nicely descriptive, and most likely will
be used relatively rarely.

[Daniel]

Post by Tim Rentsch

Post by Daniel
I tentatively went with boost's approach for tuple, iterator, and
bimap (subdirectory singular, namespace plural, class name
singular), hence cbor (subdirectory), cbors (namespace) and cbor
(class name). But I'm not enthusiastic about it (partly from
reflecting on comments on this thread)

I don't like the boost naming scheme. I understand it, and I
think I understand some of the motivations behind it, but it
grates on my low-level linguistic mental machinery, and that is
almost always a sign that somewhere a poor choice was made.

Agreed. Although I think users of a library may have a different
perspective :-) As a user of boost, I really don't care what the
namespace names are, I look them up in the online docs, and use them.
I think it's library makers that agonize over the names, as here.

Post by Tim Rentsch

Post by Daniel
and am thinking of changing it to cbor, cbor, and packed_cbor.

Did do that

Post by Tim Rentsch
Depending on what "packed" is supposed to mean, "packed_cbor" is
either pointlessly redundant or self-contradictory.

Good point. It's accepted terminology to "unpack" a cbor encoded byte array
into a form that can be more readily manipulated, and then "pack" that back
into a byte array encoded as cbor, but "packed_cbor" conjures an oxymoron,
thanks for pointing that out.

Post by Tim Rentsch
Also, using
"cbor" as the main noun is wrong: CBOR is a scheme for encoding
something, not the resulting encoding. For what I think you want
this class to represent, "cbor" should be used as an adjective,
not a noun. So either "cbor_encoded_item" or "cbor_packed_item"
would be a better choice for the class name. Yes, the name is a
little long, but it is nicely descriptive, and most likely will
be used relatively rarely.

Thanks for the suggestion, will reflect on it.

Daniel

[legalize+ (Richard)]

[Please do not mail me a copy of your followup]

Post by Jorgen Grahn
The class name should IMHO be read as in the context of the namespace,
and then cbor::cbor would just be superfluous, and say nothing about
the class itself.

In my canonical solutions to problems on the C++ language track for
exercism.io, I often ended up with a single function that was the
solution. However, I wanted to exhibit that the only thing that
should be declared in the global namespace is main(), so I put the
function in a namespace. Most of the time it ended up being foo:foo
for not having any better alternative. The context of the problems
are small enough that you generally just needed a single identifier,
but I didn't want that in the global namespace. I don't like naming
functions "process" or even worse "doit", so I settled for a little
repetition. Example:
<https://github.com/exercism/cpp/blob/master/exercises/anagram/example.h>

[Daniel]

I don't like naming functions "process" or even worse "doit",

Agreed

so I settled for a little
<https://github.com/exercism/cpp/blob/master/exercises/anagram/example.h>

Okay, but I always thought that introducing a class name the same as the
namespace name was disfavored because it introduced ambiguities, e.g.

namespace anagram
{
class anagram
{
};
}

using anagram::anagram;

int main()
{
anagram x;
}

Error: a namespace name is not allowed

Daniel

[Daniel]

Post by Daniel

Post by legalize+ (Richard)
<https://github.com/exercism/cpp/blob/master/exercises/anagram/example.h>

Okay, but I always thought that introducing a class name the same as the
namespace name was disfavored because it introduced ambiguities, e.g.
namespace anagram
{
class anagram
{
};
}
using anagram::anagram;
int main()
{
anagram x;
}
Error: a namespace name is not allowed

There's some discussion in the boost docs about the rationale for settling on "tuples" for the subnamespace for the tuple class, c.f. http://www.boost.org/doc/libs/1_55_0/libs/tuple/doc/design_decisions_rationale.html.

"The final ... solution is now to have all definitions in namespace
::boost::tuples ... The subnamespace name tuples raised some discussion. The
rationale for not using the most natural name 'tuple' is to avoid having an
identical name with the tuple template. Namespace names are, however, not
generally in plural form in boost libraries. First, no real trouble was
reported for using the same name for a namespace and a class and we
considered changing the name 'tuples' to 'tuple'. But we found some trouble
after all. Both gcc and edg compilers reject using declarations where the
namespace and class names are identical"

Daniel

[Jorgen Grahn]

Post by legalize+ (Richard)
[Please do not mail me a copy of your followup]

Post by Jorgen Grahn
The class name should IMHO be read as in the context of the namespace,
and then cbor::cbor would just be superfluous, and say nothing about
the class itself.

In my canonical solutions to problems on the C++ language track for
exercism.io, I often ended up with a single function that was the
solution. However, I wanted to exhibit that the only thing that
should be declared in the global namespace is main(),

I personally don't believe in that rule.
A namespace for a library: yes.
A namespace for a subsystem in a larger program: yes.
Namespaces just to get better-looking names in general: yes.
But for the bulk of a program I think of the global namespace as the
program's context, and am happy with it.

But then I'm unusually sensitive to repetition and duplication in
names.

/Jorgen

[legalize+ (Richard)]

[Please do not mail me a copy of your followup]

Post by Jorgen Grahn
But then I'm unusually sensitive to repetition and duplication in
names.

I agree with the tension you describe.

However, I'm purposefully doing this because I see far too many "C++
libraries" and other such things where they dump everything in the
global namespace.

I want namespaces to be visible, front-and-center, in my sample solutions.