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]

On Sun, 2018-03-25, Daniel wrote:
> 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

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

> 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

--
// Jorgen Grahn <grahn@ Oo o. . .
\X/ snipabacken.se> O o .

[Daniel]

On Monday, March 26, 2018 at 6:05:17 AM UTC-4, Jorgen Grahn wrote:
> On Sun, 2018-03-25, Daniel wrote:
> > 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
>
> 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.

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

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

[Richard]

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

Jorgen Grahn <grahn...@snipabacken.se> spake the secret code
<slrnpbhhe6.e...@frailea.sa.invalid> thusly:

>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>
--
"The Direct3D Graphics Pipeline" free book <http://tinyurl.com/d3d-pipeline>
The Terminals Wiki <http://terminals-wiki.org>
The Computer Graphics Museum <http://computergraphicsmuseum.org>
Legalize Adulthood! (my blog) <http://legalizeadulthood.wordpress.com>

[Daniel]

On Monday, March 26, 2018 at 12:05:33 PM UTC-4, Richard wrote:
>
> I don't like naming functions "process" or even worse "doit",

Agreed

> so I settled for a little
> repetition. Example:
> <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

[Jorgen Grahn]

On Mon, 2018-03-26, Richard wrote:
> [Please do not mail me a copy of your followup]
>
> Jorgen Grahn <grahn...@snipabacken.se> spake the secret code
> <slrnpbhhe6.e...@frailea.sa.invalid> thusly:
>
>>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.

[Daniel]

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]

On Mon, 2018-03-26, Daniel wrote:
> On Monday, March 26, 2018 at 6:05:17 AM UTC-4, Jorgen Grahn wrote:

...

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

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.

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

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

[Richard]

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

Jorgen Grahn <grahn...@snipabacken.se> spake the secret code

<slrnpbki3k.e...@frailea.sa.invalid> thusly:

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

[Tim Rentsch]

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]

On Friday, March 30, 2018 at 2:50:07 AM UTC-4, Tim Rentsch wrote:
>
> 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]

Daniel <daniel...@gmail.com> writes:

> On Friday, March 30, 2018 at 2:50:07 AM UTC-4, Tim Rentsch wrote:
>
>> 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]

On Monday, April 2, 2018 at 11:45:56 AM UTC-4, Tim Rentsch wrote:

> Daniel writes:
>
> > 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.

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

Did do that

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

> 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