[Development] API style guide: scoped enum or not?

Thiago Macieira thiago.macieira at intel.com
Fri May 5 07:28:44 CEST 2023


On Thursday, 4 May 2023 21:43:01 PDT Marc Mutz via Development wrote:
> Since the rename is specific to the enum at hand, there's no hope that
> such tooling exists today. However, simple semantic symbol replacement
> is an easy thing to implement in clang-tidy, yes. That could be
> accompanied by Thiago's memory_order trick and Q_DECL_DEPRECATED.

This should be doable right now for the Qt namespace.

But I don't think it should be automated. Instead, we need to put some thought 
into the new names. For the majority of them, we can probably remove the noun 
that is part of the name (Qt::MouseButton::LeftButton → 
Qt::MouseButton::Left), but sometimes the change isn't obvious. We can also fix 
historical mistakes, like the colour names in Qt::GlobalColor being lowercase. 
Some of them won't work for other reasons, like Qt::Key_I can't become 
Qt::Key::I because the identifier I is defined in <complex.h> as a macro for the 
imaginary unit[1] (this shouldn't affect C++, but broken implementations 
exist).

There are also enums that may serve multiple purposes, like the enumerator 
Qt::KeepEmptyParts. Right now, it's part of SplitBehavior, but it could just 
as well be used for joining. Or not, see [2] for discussion.

And there are all the flags. For the vast majority of them, the only documented 
name is the QFlags typedef. For those whose QFlags typedef is just the plural 
of the enum, code like this is probably acceptable:

  Qt::Edges edges = Qt::Edge::Top | Qt::Edge::Left;

But for those that use a very name, the API becomes cumbersome:

  Qt::Alignment al = Qt::AlignmentFlag::Left;

Can we do better? With C++20 using enum (GCC 11, Clang 13, so not in my 
proposal) we could easily.

[1] https://en.cppreference.com/w/c/numeric/complex/I
[2] https://codereview.qt-project.org/c/qt/qtbase/+/471246?usp=email

-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Cloud Software Architect - Intel DCAI Cloud Engineering
-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 5152 bytes
Desc: not available
URL: <http://lists.qt-project.org/pipermail/development/attachments/20230504/fe2e8b9b/attachment.bin>


More information about the Development mailing list