[Development] Naming convention for (scoped) enums

[Simon Hausmann]

On 8/15/18 9:32 AM, Alex Blasche wrote:
>
>> -----Original Message-----
>> From: Tor Arne Vestbø
>> 1. Scoped enums (enum class) for the sake of avoiding name clashes is useful for
>> global enums, but when the enum lives inside a class, the chance that we’ll see a
>> naming clash is minor, and using scoped enums in that case arguably has
>> negative effects on code writability/readability. As a result, we should update
>> the policy to not mandate scoped enums when the enum lives inside a class.
> I don't think we have ever not permitted exceptions to official policy. Therefore, take it for granted that the policy can be ignored such as in the case presented by Allan. Having said that the default should be the use of scoped enums even inside of classes.
>
> I don't consider the longer names detrimental for writability and usability. Writability is easily solved with code completion and readability is actually better because the type adds additional context info. To cite an example from Shawn's patch:
>
> QQuickPointerDevice::Finger
> QQuickPointerDevice::Mouse
>
> is far less descriptive than (and not compliant to current naming convention)
>
> QQuickPointerDevice::PointerType::Finger
> QQuickPointerDevice::DeviceType::Mouse.
>
> The uninitiated reader of the code cannot see the additional type context when reading code and therefore someone might interpret Finger as a device type too. That's exactly what the existing unscoped enum policy tries to fix. Scoped enums provide this feature out of the box. Another example of a good naming policy (IMO) is QAbstractSocket (never mind the technical limitations). Here we could shorten the enum names using scoped enums:
>
> QAbstractSocket::SocketError::ConnectionRefusedError -> QAbstractSocket::SocketError::ConnectionRefused (or even QAbstractSocket::Error::ConnectionRefused)
>
> Name clash prevention was only ever secondary to readability.
>
We don't need scoped enums to improve readability though, that doesn't 
seem like an argument. To take the finger/mouse example, we would use

     QQuickPointerDevice::FingerPointer

or

     QQuickPointerDevice::PointerType_Finger

and you get exactly the same benefit, no?

Meanwhile, QQuickPointerDevice::DeviceType::Mouse is not improving 
readability IMO but adding noise. The name "PointerDevice" gives the 
exactly the context required to get an idea about the meaning of 
"Mouse". API is like documentation, there is a balance to be struck 
between conciseness and verbosity. If text is too verbose, it's hard to 
read. If text is too concise, then it may fail to convey crucial 
information.


So we have three arguments for scoped enums:

     1. Avoids clashes

     2. Improves readability

     3. Adds type safety


After some of enum class use myself and seeing their use in code 
reviews, I feel that to avoid (1) and achieve (2) we don't need enum 
classes. After all we've solved this before with prefixing.

I do buy a little into the type safety argument, but I feel that affects 
more the internal use (where we sometimes do things on a low-level and 
need it) in contrast to our API where we can make sure that the enums 
are used in good context.

The risk I start to see with enum classes is that they present an 
opportunity where we can spend less time thinking about good names in 
the API. They present a tool that allow us to just use any name we like 
and not worry so much about the big picture of the class(es) they appear in.

If we decide to allow deciding on a case-by-case basis, then I encourage 
everyone to carefully look at newly introduced enums, their values and 
their context in the upcoming "API review season".


Simon


>> 2. Scoped enums for the sake of type safety is a valid use case, but can be solved
>> by promoting a warning to an error, and as such shouldn’t block us moving
>> forward with #1.
> I don't see how a policy of elevating warnings to errors is better that using a language inbuilt error due to strong type safety.
> --
> Alex
> _______________________________________________
> Development mailing list
> Development at qt-project.org
> http://lists.qt-project.org/mailman/listinfo/development