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

["Einar Nilsen-Nygaard (einarnn)" <[e-mail]>]

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/>