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

[Marc Mutz]

On 02.05.23 10:58, Volker Hilsheimer via Development wrote:
> During the header review, but also in API discussions leading up to it, we had a few cases where it would have helped if we had clearer guidelines about when to use scoped enums, and when not.

Was there some consensus here? We're discussing this _again_ in the 6.6 
review...

Let me propose the following, separate issues, so we have something 
concrete to +1 or -1:

[All capitalized words have the meaning of IETF RFCs]

A) new enums MUST have an explicit underlying type¹²

For unscoped enums, the compiler otherwise picks one, possibly resulting 
in BiC when new addtions change the underlying type or otherwise just 
warnings because one compiler uses a signed and the other an unsigned 
type (most recent exmaple: QTBUG-113792). For scoped enums, the type is 
int, but probably not always, and why require the reader of the code to 
know the C++ rules when we can make it explicit?

B) new enums MUST be scoped, also when nested in classes¹²

Type safety > verbosity. Qt has never preferred brevity over verbosity 
when it comes to readability, and while the use of short identifiers 
makes code often more readable than using long ones, C++20's `using 
enum` feature empowers users to choose between brevity and verbosity on 
a per-use basis. Since we should be designing for the future and not the 
past, this removes the major objection for scoped enums. C++17 doesn't 
matter. If we really want leaking, we can use constexpr variables of 
scoped enum type in lieu of enumerators.

C) scoped enums SHOULD NOT repeat (part of) an enum's type name in the 
enumerators²

This was a work-around from the times of C/C++98 when you could neither 
scope the value of an enumeration nor prevent the leakage of enumerator 
names into the enclosing scope. We have both now in C++11: any 
enumerator can be scoped and scoped enums don't leak the name into the 
enclosing scope anymore.

I cannot rule out that sometimes some part of the enum's type may make 
sense in an enumerator's name, but not consistently in all of them just 
because one of them needs it etc, so this is a SHOULD, not a MUST.

I have been told today that QML allows scoped C++ enums to be used 
without the scope. If this is true, it should be fixed to always require 
the scope, because otherwise the argument goes "but in QML, the scope 
isn't visible, so a part of the enum type name must be included in the 
enumerators".

¹ except when C compatibility is required
² applies to all enums come Qt 7

It would be good if we could have clarity on A-C before we finish up the 
6.6 API review.

Thanks,
Marc

-- 
Marc Mutz <marc.mutz at qt.io>
Principal Software Engineer

The Qt Company
Erich-Thilo-Str. 10 12489
Berlin, Germany
www.qt.io

Geschäftsführer: Mika Pälsi, Juha Varelius, Jouni Lintunen
Sitz der Gesellschaft: Berlin,
Registergericht: Amtsgericht Charlottenburg,
HRB 144331 B