Subject: [YANG] so many naming scopes

From: Andy Bierman <[email-masked]>
Date: Thu, 03 Jan 2008 10:44:16 -0800

Hi,

Sec. 6.2 lists several naming scopes for various YANG constructs.
Most of it seems fine, except I am concerned about the confusion factor
that can result:

module foo {
   namespace "http://example.com/foo-ns";
   prefix "foo";
   description "do you have anything without foo in it?";

   typedef foo {
     type int32;
   }

   grouping foo {
     leaf x { type foo; }
   }

   container foo {
     leaf a { type foo; }
     uses foo;
     choice b {
       case foo {
         leaf c { type foo; }
       }
       case b {
         container d {
           uses foo;
         }
       }
     }
   }

}

Is this much flexibility such a good idea?
I don't think the lack of individual naming scopes for every
type of identifier has been a big problem in the SNMP world.

Andy

_______________________________________________
YANG mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/yang

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 03 Jan 2008 20:49:50 +0100 (CET)

> Is this much flexibility such a good idea?

Maybe not.

> type of identifier has been a big problem in the SNMP world.

No, but I don't think we should have a single flat namespace for
identifiers like SNMP has.  I can live with one namespace per nesting
level though.

Earlier we had a separate namespace for rpcs and a separate for
notifications as well, but the drawback with that was that we couldn't
use 'augment' to augment these, so we had to have separate statements
'augment-rpc' and 'augment-notification'.  Having a single namespace
actually made 'augment' more flexible.

/martin

---

From: Andy Bierman <[email-masked]>
Date: Thu, 03 Jan 2008 12:19:08 -0800

> identifiers like SNMP has.  I can live with one namespace per nesting

Yes, of course one naming scope (the term namespace is taken)
amongst siblings, except nested typedef and grouping names
cannot mask similar definitions within an ancestor node,
or globally within the same module.  (This part already in the draft.)

OK:

   container foo {
     container foo { ... }
   }

Not OK:

  container foo {
    typedef foo { type int32; }
    container foo {
      typedef foo { type int32; }    // invalid! masks previous typedef
      leaf foo { type foo; }
    }
  }

Only the top level definitions can be exported to other modules.
SMIv2 rules are too restrictive for XML naming, but the ability is lost
to import nested leafs like 'ifIndex' in addition to top-level objects
like 'ifTable'.  The schema-nodeid Xpath form must be used
to access such nodes (/if:ifTable/if:ifIndex).

Andy

---

From: Phil Shafer <[email-masked]>
Date: Thu, 03 Jan 2008 23:35:46 -0500

>or globally within the same module.  (This part already in the draft.)

Isn't this dancing on the line of CLR?  Where's the logic of saying
"don't do that" when there's really no ambiguity?  If I say "leaf 
foo { .. } typedef foo { .. }", my use of "type foo" is clear.
Is there a situation where isn't not clear to the compiler
what is meant?  Are we trying to get the compiler to enforce
style rules when the language proper doesn't require them?

Thanks,
 Phil

---

From: Martin Bjorklund <[email-masked]>
Date: Fri, 04 Jan 2008 08:32:08 +0100 (CET)

> style rules when the language proper doesn't require them?

One reason is the augmentation of groupings that we discussed (I'm
planning to write about this disussion to the list, RSN).  If we allow
augment of groupings, then the grouping identifiers must share the
namespace with data-defs/rpc/notifs.

/martin

---

From: Balazs Lengyel <[email-masked]>
Date: Fri, 04 Jan 2008 10:50:45 +0100

While the use of many naming-scopes is understandable for the compiler is it easy to understand 
for the reader ? IMHO no.
I like Andy's proposal.
Balazs

-- 
Balazs Lengyel                       Ericsson Hungary Ltd.
TSP System Manager
ECN: 831 7320                        Fax: +36 1 4377792
Tel: +36-1-437-7320     email: [email-masked]

---

From: Andy Bierman <[email-masked]>
Date: Fri, 04 Jan 2008 04:01:41 -0800

Balazs Lengyel wrote:
> While the use of many naming-scopes is understandable for the compiler 
> is it easy to understand for the reader ? IMHO no.

That is my concern as well.

As in any engineering decision, we have to weigh the trade-offs.
How much overall value is lost by forcing DM writers to
maintain one set of identifiers (using up some of the 63 chars
of minimum uniqueness), vs. the confusion of having the same
identifier value mean many different things, even within the same file.

Andy

>> "don't do that" when there's really no ambiguity?  If I say "leaf foo 
>> { .. } typedef foo { .. }", my use of "type foo" is clear.

---

From: "Bert Wijnen - IETF" <[email-masked]>
Date: Fri, 4 Jan 2008 13:08:16 +0100

> identifier value mean many different things, even within the same file.

If the language can accept and easily handle it, then maybe we should
allow it to do so and not create CLRs.
A good and smart data-model-developer would/should still do the right
thing and make things as clear as possible for the user/reader of the
data-model. That means that one uses a style of definitions that is
obvious and clear and so would not cause confusion.

It is similar to using all sorts of short abbreviations/acronyms in names
of variables and such versus spelling out a longer name. The longer name
will make it much more readable/understandable for the new person who
read the module for the first time. That does not mean we must pre-scribe
that short-names/acronyms are not allowed.

> > I like Andy's proposal.

So I like the underlying reasons, but I am not sure we have to enforce it
in the langauge.

Bert

---

From: Andy Bierman <[email-masked]>
Date: Fri, 04 Jan 2008 04:46:33 -0800

> So I like the underlying reasons, but I am not sure we have to enforce it

<implementor-hat-on>
I don't mind your suggestion at all, since I already coded it
the way it's defined now.  It is not much more work to keep
typedefs, groupings, and objects (data/rpc/notification) separate.
</implementor-hat-on>

There is a sentence in sec. 6.2 about SHOULD not have names that are different
just in case.  There could be another sentence that says all identifiers
(of these 3 types) SHOULD be unique.  IMO, standard data models
do not need to overload these identifiers.  There are 63 chars,
instead of 32 in SMI, and (for data) it is only sibling nodes, not every node.

Andy

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Mon, 7 Jan 2008 09:02:24 +0100

> style rules when the language proper doesn't require them?

I agree - lets not make coding styles a part of the language design.

/js

-- 
Juergen Schoenwaelder           Jacobs University Bremen gGmbH
Phone: +49 421 200 3587         Campus Ring 1, 28759 Bremen, Germany
Fax:   +49 421 200 3103         <http://www.jacobs-university.de/>

---

From: Andy Bierman <[email-masked]>
Date: Mon, 07 Jan 2008 06:50:44 -0800

> I agree - lets not make coding styles a part of the language design.

Then let's change this sentence in sec 6.2:

    All identifiers defined in a namespace MUST be unique and SHOULD NOT
    only differ in case.

Change to:

   All identifiers defined in a namespace MUST be unique.

Andy

---

From: "tom.petch" <[email-masked]>
Date: Tue, 8 Jan 2008 09:40:45 +0100

----- Original Message -----
From: "Bert Wijnen - IETF" <[email-masked]>
To: "Andy Bierman" <[email-masked]>; "Balazs Lengyel"
<[email-masked]>
Cc: <[email-masked]>
Sent: Friday, January 04, 2008 1:08 PM
Subject: RE: [YANG] so many naming scopes

> obvious and clear and so would not cause confusion.

Agree absolutely, but, sadly, developers may not be either good or smart or
both.  And your definition of smart may not be mine, it may be someone who is so
clever that they come up with something that is incomprehensible to the mere
mortals who inherit what they have produced.

A goodly part of my coding has been maintenance, having to reverse engineer the
existing language before being able to change it; the best developers produce
something that is so simple, so obvious that everything thinks 'I could have
done that' - except that they couldn't.  The worst developers - who are often
very clever - produce something that needs a Ph D in Philosophy to unravel.

There are languages where no word is reserved, where the same symbol(word) can
be used for label, type, module etc.  XML is arguable worse with the ability to
start a fresh namespace on alternate lines.  These belong in the bin.

So, I think that having restraints is a good thing, for the benefit of the good
and smart maintainers who have to put up with the output of diabolical
developers.  The number of discrete naming scopes that can appear in a 200-line
module should be severely restricted.

Tom Petch

---

From: Phil Shafer <[email-masked]>
Date: Tue, 08 Jan 2008 17:30:25 -0500

>start a fresh namespace on alternate lines.  These belong in the bin.

That's a very strong statement, given that the motivation for
avoiding reserved words is typically future proofing.  Don't paint
it as a universally bad feature.

For example, if I use "action" as a leaf in my model and the next
version of YANG adds a feature that uses "action" as a keyword, my
model is broken and needs repair.

Many languages reserve unused keywords just on the odds they will
need them in the future, but they are seldom right.  By keeping the
namespace of user-defined stuff out of the namespace of keywords,
YANG avoids this issue entirely.  As the number of modules defined
in YANG approaches the number that are defined in SMI, this will be
an important language feature.

Thanks,
 Phil

---

From: "tom.petch" <[email-masked]>
Date: Wed, 9 Jan 2008 16:22:21 +0100

----- Original Message -----
From: "Phil Shafer" <[email-masked]>
To: "tom.petch" <[email-masked]>
Cc: "Bert Wijnen - IETF" <[email-masked]>; "Andy Bierman"
<[email-masked]>; <[email-masked]>
Sent: Tuesday, January 08, 2008 11:30 PM
Subject: Re: [YANG] so many naming scopes

> an important language feature.
Yes, I expressed myself strongly, perhaps as a result of spending time in 2007
with XML documents where there was widespread use of an element named <element>
as well as one named <attribute>; I wish that XML had reserved those words:-(  I
accept that it is a trade off, and devising a language without reserved words is
an achievement; but I find it costs usability when eg you can have labels such
as 'if' and 'then' and variables such as 'for' and 'case'.  I mean, it is sort
of obvious, you are writing this small simple program that will only ever have
one case construct so it is natural to name the associated variable 'case'.

If a language has concepts which are widely written about in English - perhaps
container, leaf, index, key would qualify - then I would prefer those to be
reserved, else someone someday will use them.

Tom Petch

---

From: Andy Bierman <[email-masked]>
Date: Wed, 09 Jan 2008 08:57:49 -0800

> reserved, else someone someday will use them.

My concern is that even though compilers and YANG experts are aware
of the 6 different naming scopes defined in sec. 6.2, perhaps newbies
would be confused by seeing data models that mix them all together.

Now you bring up a new twist:

    typedef typedef {
      type string;
    }

    leaf leaf {
      type typedef;
    }

IMO, there needs to be guidelines (in the form of SHOULD NOT text)
that says not to use YANG keywords for identifiers and not
to use the same values for typedefs, groupings, and object names,
even though it is allowed.

In IETF-speak, a 'SHOULD' means vendors can do what they want in their DMs,
but WGs will have to justify any violations of the CLR to the IESG.

Andy

---

From: Phil Shafer <[email-masked]>
Date: Wed, 09 Jan 2008 12:28:41 -0500

>as well as one named <attribute>; I wish that XML had reserved those words:-(  I

That might sounds wise up until the moment when you need to define
XML for chemical elements (<element>helium</>) or character attributes
(<attribute>fluffy</>).  Forcing folks to choose non-obvious words
because the DML uses them is bad.  key and index are two examples
where the modeler should be able to use them if they are exactly
the term they need.

Thanks,
 Phil

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 9 Jan 2008 23:46:27 +0100

> even though it is allowed.

Usage guidelines and "coding styles" are valuable. But they should not
be part of the language itself. The example above is not ambiguous and
easy to parse for a machine - even though it might look stupid to most
humans.

I do remember the fun I had when C++ came along with the 'new'
keyword. The namespaces we have in YANG help to avoid such problems so
that we can add keywords to YANG without risking to break something.

/js

---

From: Andy Bierman <[email-masked]>
Date: Wed, 09 Jan 2008 15:04:46 -0800

> that we can add keywords to YANG without risking to break something.

Except that YANG has embedded coding style text already,
such as the sentence about SHOULD NOT differ only in case.
Names such as foo and Foo and perfectly valid.  There is
no reason whatsoever to have this text, same as a CLR
about not having grouping foo and typedef foo, other than
to enforce a coding style.  (My suggestion was SHOULD, not MUST.)

Standards are full of non-binding text (SHOULD, MAY) because
it can encourage interoperability.  Some people think
multi-vendor interoperability is more important for a
standard than single-vendor flexibility.

Andy

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 10 Jan 2008 00:24:27 +0100

> to enforce a coding style.  (My suggestion was SHOULD, not MUST.)

So lets remove this "SHOULD NOT differ only in case" rule from the
language specification and lets start a guidelines document (or an
appendix for simplicity) where we collect such guidelines.

/js

---

From: Phil Shafer <[email-masked]>
Date: Wed, 09 Jan 2008 21:34:56 -0500

>appendix for simplicity) where we collect such guidelines.

Sounds great.

Thanks,
 Phil

---

From: Balazs Lengyel <[email-masked]>
Date: Thu, 10 Jan 2008 08:56:58 +0100

> easy to parse for a machine - even though it might look stupid to most
I think our yardstick should be whether the example is easy to understand for humans. "Easy for 
machine" is far from enough.

Balazs

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 10 Jan 2008 09:09:11 +0100

On Thu, Jan 10, 2008 at 08:56:58AM +0100, Balazs Lengyel wrote:
> I think our yardstick should be whether the example is easy to
> understand for humans. "Easy for machine" is far from enough.

Sorry, I fail to get your point. Do you want to have a rule in the
language saying "people must not use stupid identifiers"? This is
really what we are talking about here and my point is that trying to
define what makes a stupid identifier is a waste of time for the
language definition itself. A good language will deal with stupid and
non-stupid identifiers the same way.

/js

PS: We really need an April 1st RFC defining a standard for good code
    so that by claiming compliance to this RFC, we will eliminate all
    bad smelling code from the world. ;-)

---

From: "Bert Wijnen - IETF" <[email-masked]>
Date: Thu, 10 Jan 2008 10:18:29 +0100

I also like to move the "SHOULD, SHOULD NOT, MAY and similar
style information to a guidelines document. 

Be aware though, that this guidelines document will become our
CLR guide. Similar to how RFC4181 became our CLR document for
MIB modules. I am not saying that is bad. I in fact like some
rules for standardized Data Models such that we will see
consistency. It will help make things easier to use and read.

Bert Wijnen 

> -----Oorspronkelijk bericht-----
> Van: Phil Shafer [mailto:[email-masked]]
> Verzonden: donderdag 10 januari 2008 3:35
> Aan: [email-masked]
> CC: [email-masked]
> Onderwerp: Re: [YANG] so many naming scopes 
> 
>