Re: [boost.async] new name

From: Andrey Semashev (andrey.semashev_at_[hidden])
Date: 2023-10-12 12:18:09

On 10/12/23 03:51, Klemens Morgenstern via Boost wrote:
> Given the renaming requirement, I'd like to query the list if there
> are any objections to any of the following names:
> 
> async.core
> await
> co_async / cosync
> co20 / cor20

I'm not going to pick any name, but will comment on the process of
picking itself. While picking a name, consider the alternative spellings
that will be used in various places, such as:

- In written correspondence such as this mailing list and GitHub issues.
Note that there are official guidelines[1] as to how a library should be
referenced, which basically boils down to "Boost.LibraryName" or "the
LibraryName library". Sometimes people use just "LibraryName" for short,
when it is obvious to refer to a Boost library. Note the CamelCase with
no spaces.

- On Boost website, such as the library list[2] and release notes[3].
There's a variety of approaches taken there, but "Library Name" (i.e.
Camel Case with spaces) seems to be the most common, as it is more
readable English.

- In URLs and filesystem paths. This primarily concerns the GitHub
repository name, and is usually spelled as "library_name" (lower-case
with underscores).

- In code, such as namespace/class/function names, macro name
decoration, Boost.Build and CMake target names and so on. For macros, it
should be "BOOST_LIBRARY_NAME" (all-caps with underscores, prefixed with
"BOOST_"), for others it should be "library_name" (lower-case with
underscores). Sometimes there is a clash between the namespace name and
a class or function name, in that case the namespace name should be
different, but not too much. A few examples are:
Boost.Align/boost::alignment/boost::alignment::align(),
Boost.Tuple/boost::tuples/boost::tuples::tuple<>.

So, a good library name should look good and unambiguous in all these
spellings, and preferably easy to type. From this perspective, names
using special characters like underscores and dots are more problematic
and less preferred. Multi-word is ok, as long as it is easy to
unambiguously map to one of the spellings mentioned above, but
single-word is better still. Remember that people will be typing the
library name in correspondence and code, hopefully for many-many years
ahead, and it would be prudent to minimize the risk of spelling errors now.

A note about "async.core" and alike. Such naming suggests that "core" is
a part of a larger "async" library that must contain some other parts as
well. We have a precedent, Boost.Spirit, which contains Qi, Karma,
Classic and X3. This also translates to namespace structure (there are
boost::spirit::qi, boost::spirit::karma and so on) and macro names. My
understanding is that this is not the case with your library, so
"async.core" would be confusing and misleading.

[1]: https://www.boost.org/community/policy.html#lib_names
[2]: https://www.boost.org/doc/libs/1_83_0/
[3]: https://www.boost.org/users/history/version_1_83_0.html