Re: [yang-doctors] guideline for enum and value?

[Jan Lindblad <[e-mail]>]

Einar,

FWIW, the ConfD NETCONF server implementation has a *programming API* which is stable against enum order changes in the YANG as described below. I.e. that can still be an implementation decision. I agree, though, that depending on implicit order is risky, and that's exactly why we avoid this in the APIs.

/jan

> On 14 Feb 2018, at 17:19, Einar Nilsen-Nygaard (einarnn) <[e-mail]> wrote:
> 
> For me it's about who the values of the enums are for, and the impact on model evolution in different places. The enum values are explicitly intended as for model implementers to use, and have no real meaning to model consumers as the canonical representation is the string identifier. However, once a value is assigned via a "value", that value may never change. I have seen developers naively assign explicit values from other sources (e.g. system header files on the OS) and then inadvertently see problems when they implement the model on top of a new OS, where the value matching the symbol is not the same, and so the developers just (illegally) changed the value in the value clause. This still has zero impact on the end consumer of the model, as they deal with the string, but is a backwards compatibility violation that need not have happened.
> 
> In general, I think embedding values that are primarily targeted to implementers of a model in what is also the external format is just not all that helpful.
> 
> Not a huge deal, but reduces coupling, reduces opportunity for inadvertent backwards-compatibility breakage, and encourages better implementation code/model hygiene as all parties will be encouraged to utilize symbols rather than flawed values. I would like to see both consumers and implementers of models get to the point where:
> 
> type enumeration { enum foo; enum bar; }
> 
> and
> 
> type enumeration { enum bar; enum foo; }
> 
> ...are ultimately treated the same and such that reordering of symbols doesn't break things. I've seen enough broken code based on order-dependent integer value assignments combined with people using the values instead of symbols to last several lifetimes, and anything we can do to remove opportunities for mistakes seems like a good thing.
> 
> Cheers,
> 
> Einar
> 
>> On Feb 14, 2018, at 3:59 PM, Juergen Schoenwaelder <[e-mail] <mailto:[e-mail]>> wrote:
>> 
>> On Wed, Feb 14, 2018 at 04:47:40PM +0100, Juergen Schoenwaelder wrote:
>> 
>>>> And:
>>>> 
>>>>  Do not use explicit 'value' statements, except if:
>>>>     o the enum corresponds to some standard integer value, or
>>>>     o you update the set of enums by inserting new enums in the middle of
>>>> the list
>>> 
>>> I am not sure why we would recommend this.
>>> 
>> 
>> More specifically, I do not see why
>> 
>>  type enumeration { enum foo { value 0; }; enum bar { value 1; }; }
>> 
>> is to be avoided in favor of
>> 
>>  type enumeration { enum foo; enum bar; }
>> 
>> given that they mean the same and the first one is explicit and robust
>> to changes while the second one must be handled with care (only append
>> enums, never reorder enums). Yes, clueful YANG authors can handle the
>> later fine as they will understand that if order changes are needed,
>> you have to move to explicit value assignments. My fear is that not
>> all YANG authors will be aware of this (but then many of those authors
>> likely also do not read guidelines).
>> 
>> /js
>> 
>> -- 
>> Juergen Schoenwaelder           Jacobs University Bremen gGmbH
>> Phone: [phone]         Campus Ring 1 | 28759 Bremen | Germany
>> Fax:   [phone]         <https://www.jacobs-university.de/ <https://www.jacobs-university.de/>>
> 
> _______________________________________________
> yang-doctors mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/yang-doctors