[Development] Naming convention for (scoped) enums

[Jan-Arve Sæther]

For me it seems that enum classes can help us create a more structured API, because they also gives more semantic information, e.g:

QQuickPointerDevice::PointerType::Finger

gives more information than
QQuickPointerDevice::Finger


For example, when doing code completion if I type "QQuickPointerDevice::" it will give me _all_ members of QQuickPointerDevice (which I always have found a bit annoying), but with an enum class I can type "QQuickPointerDevice::PointerType::" and I will get listed only the valid values (finally).


With the extra semantic I can even assume that the associated property for the value QQuickPointerDevice::PointerType::Finger is called pointerType (which it is). (I admit this is not always the case, but maybe it should be a goal).


And having it up for discussion for each review whether an enum should be class enums or not just sounds like were planning for lots of bike-shedding ahead.

Last, maybe enum classes will lead to more ugly static_cast inside Qt, but that's a cheap price to pay if it gives our users a better API (my point is that a few awkward internal static_cast should not influence how our public API is).

my 5 øre


---
Jan Arve Sæther
Senior Software Engineer


________________________________
Fra: Development <development-bounces+jan-arve.saether=qt.io at qt-project.org> på vegne av Tor Arne Vestbø <Tor.arne.Vestbo at qt.io>
Sendt: fredag 31. august 2018 11.56.15
Til: Alex Blasche
Kopi: development at qt-project.org
Emne: Re: [Development] Naming convention for (scoped) enums

I think Simon’s reasoning in the review that spurred this discussion summarises it nicely:

> On 31 Aug 2018, at 10:24, Simon Hausmann (Code Review) <gerrit-noreply at qt-project.org> wrote:
>
> Simon Hausmann has posted comments on this change.
>
> Change subject: Convert QQEventPoint and QQPointerDevice enums to enum classes
> ......................................................................
>
>
> Patch Set 7:
>
> As excited I was initially with enum classes, I also start to dislike them when looking at their use.
>
> The counter example, QQuickPointerDevice::Mouse, is awesome. QQuickPointerDevice::DeviceType::Mouse looks worse.
>
> Always scoping leads to redundancy and never scoping leads to clashes. Enum classes don't allow us to choose, they force us into the longer names. The previous policy of prefixing _when needed_ gave us the flexibility to have lean names when we could and longer names when required. For example QuickItem::ItemHasContents.
>
> So in terms of naming I find enum classes not truly winning. Perhaps they make us more lazy in finding the best names, because just putting whatever we have in an enum class "takes care of it".
>
> The remaining argument in favor of enum classes is the type safety they add. But at least inside Qt I've often seen it become an anti-pattern because we do things in a more low-level fashion and need to cast to an int sometimes, for example.
>
> Given the names in this very API, I also disagree with commit message statement that the existing scoping is insufficient. (See QQuickPointerDevice::GrabState::GrabExclusive)

Based on the disagreement on how and when to use scoped enums, I think we should change the style policy to:

 - always recommend using scoped enums for global enums
 - describe the pro’s and con’s of scoped enums inside classes
         - ask the developer to consider each case individually
                - and use good judgement in choosing one or the other

Tor Arne
_______________________________________________
Development mailing list
Development at qt-project.org
http://lists.qt-project.org/mailman/listinfo/development
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/development/attachments/20180831/754eb54e/attachment.html>