Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Clarify that zero values bitfield helper enums should not be used
Resolves #433 ## Problem The zero values defined in helper enums encourage incorrect usage of the bitfields. The typical incorrect code looks like this: ```proto enum DataPointFlags { FLAG_NONE = 0; FLAG_NO_RECORDED_VALUE = 1; // Bits 2-31 are reserved for future use. } ``` ```go if datapoint.Flags == FLAG_NONE { // do something when there is no recorded value } ``` This is incorrect because it does not take into account that the Flags field can be extended in the future to use the reserved bits. The `if` statement above will be incorrect if any other bit is set. The correct code looks like this: ```go if (datapoint.Flags & FLAG_NO_RECORDED_VALUE) == 0 { // do something when there is no recorded value } ``` ## Solution To prevent this mistake some additional comments are added and the zero value in the enum is prefixed with an underscore to discourage its use. ## Alternates Tried I also tried to remove the zero values from enums altogether, but it turned out to be impossible. I tried a few possible approaches and none worked. Protobufs [require that enums start with a 0 value](https://protobuf.dev/programming-guides/proto3/#enum). If you try to omit it you get a compilation error: ``` opentelemetry/proto/metrics/v1/metrics.proto:325:28: The first enum value must be zero in proto3. ``` Alternatively, trying to use a dummy name, e.g.: ``` enum DataPointFlags { _ = 0; FLAG_NO_RECORDED_VALUE = 1; } ``` Fails Objective-C generator: ``` error: got empty string for making TextFormat data, input: "", desired: "_". ``` Also tried declaring it reserved as the doc says should be possible: ``` enum DataPointFlags { reserved 0; FLAG_NO_RECORDED_VALUE = 1; } ``` but get an error again: ``` opentelemetry/proto/metrics/v1/metrics.proto:327:28: The first enum value must be zero in proto3. ```
- Loading branch information