Subject: Re: [netmod] Camel Case versus hyphenation

From: Kent Watsen <[email-masked]>
Date: Sat, 1 Jan 2022 13:30:36 +0000

The fist couple paragraphs here apply: https://datatracker.ietf.org/doc/html/rfc8407#section-4.3.1

I think that it should be “open-wait” (not openwait).  Mimicking RFC values is not as important as having consistency in YANG-driven UI.

Happy 2022 y’all!  :)

K. 

> On Dec 31, 2021, at 7:50 AM, tom petch <[email-masked]> wrote:
> 
> A number of protocols name protocol values using camel case, protocols such as TCP, BGP and PCEP (RFC5440).  YANG does not like camel case and so some YANG module authors put hyphens in instead, so that OpenWait and KeepWait become open-wait and keep-wait. (draft-ietf-pce-pcep-yang)  
> 
> I strongly believe that the YANG identifiers should follow the protocol identifiers but can see that the absence of camel case can make them harder to read, to follow, perhaps when part of a compound identifier such as peer-keepalive-timer.
> 
> Which is then better, openwait or open-wait?  Is there some factor that makes one preferable.
> 
> Tom Petch
> _______________________________________________
> netmod mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod

---

From: Randy Presuhn <[email-masked]>
Date: Sat, 1 Jan 2022 10:21:15 -0800

Hi -

On 2022-01-01 5:30 AM, Kent Watsen wrote:
> The fist couple paragraphs here apply: 
> https://datatracker.ietf.org/doc/html/rfc8407#section-4.3.1 
> <https://datatracker.ietf.org/doc/html/rfc8407#section-4.3.1>
> 
> I think that it should be “open-wait” (not openwait).  Mimicking RFC 
> values is not as important as having consistency in YANG-driven UI.

The cited text supports the argument that one could use "OpenWait".
In particular, "Uppercase characters, the period character, and
the underscore character MAY be used if the identifier represents
a well-known value that uses these characters."  Cases like "OpenWait"
seem to be the reason that the preference for lower case is a "SHOULD"
rather than a "MUST".  With such cases explicitly accounted for in the
standard, there's no reason to kluge around them.

Randy

---

From: Jürgen Schönwälder <[email-masked]>
Date: Sat, 1 Jan 2022 20:25:56 +0100

> Which is then better, openwait or open-wait?  Is there some factor that makes one preferable.

I grepped the RFCs and it seems OpenWait is only used by PCE/PCEP. I
am not sure where TCP (RFC 793) uses camel case, I did not spot
anything. BGP (RFC 4271) seems to use camel case in the definition of
attributes used by the finite state machine. That said,
draft-ietf-idr-bgp-model-12.txt uses leaf names such as hold-time.

I agree with Kent that the consistency of the management API must be
considered when deciding whether an exception of the "SHOULD be
lowercase" rule is justified. I think draft-ietf-pce-pcep-yang-17.txt
follows the "SHOULD be lowercase" rule and this is just fine.

/js

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

---

From: tom petch <[email-masked]>
Date: Tue, 4 Jan 2022 09:57:38 +0000

From: Kent Watsen <[email-masked]>
Sent: 01 January 2022 13:30

<tp>
Indeed they do.  I had forgotten that.

What triggered  my post was a review in 2021 (AD, YANG Doctor) which told an author to use lower case since YANG did not use upper case and I took that on board - I should have been more circumspect and intend to do so in future.

Tom Petch

Happy 2022 y’all!  :)

K.

Tom Petch

---

From: tom petch <[email-masked]>
Date: Tue, 4 Jan 2022 11:01:16 +0000

From: Jürgen Schönwälder <[email-masked]>
Sent: 01 January 2022 19:25

> Which is then better, openwait or open-wait?  Is there some factor that makes one preferable.

I grepped the RFCs and it seems OpenWait is only used by PCE/PCEP. 

<tp>
Yes, it is PCEP that has made me raise this.  PCEP (RFC5440) has Keepalive, OpenWait.  pcep-yang has keepalive,  open-wait which I thought wrong.

I am not sure where TCP (RFC 793) uses camel case, I did not spot
anything. 

<tp>
TCP likes hyphenation FIN-WAIT, CLOSE-WAIT which RFC1122 follows with keep-alive but in places 793bis has Keep-Alive ie both!

BGP (RFC 4271) seems to use camel case in the definition of
attributes used by the finite state machine. That said,
draft-ietf-idr-bgp-model-12.txt uses leaf names such as hold-time.

<tp>
Yes and I think that wrong. For me the FSM is close to the code and so to the YANG model and so gives the correct identifiers to be used.  opsawg-l3sm-l3nm uses hold-time which I commented on but my comment was disregarded.

<tp>

Well, consistency with what? For me that is the protocol RFC that is the starting point and having YANG module authors going off in another direction, albeit consistently, is likely to be a source of confusion.

Tom Petch

/js

---

From: Jürgen Schönwälder <[email-masked]>
Date: Tue, 4 Jan 2022 12:26:44 +0100

> Well, consistency with what? For me that is the protocol RFC that is the starting point and having YANG module authors going off in another direction, albeit consistently, is likely to be a source…

If someone tells a human operator over the phone to set the wait time
to 42, then it is likely that the operator assumes the leaf is called
wait-time. Many network operators are not state machine implementors
and they likely appreciate consistency at the management interface
more than consistency with the spelling in some protocol specs.

/js

-- 
Jürgen Schönwälder              Jacobs University Bremen gGmbH
Phone: +49 421 200 3587         Campus Ring 1 | 28759 Bremen | Germany
Fax:   +49 421 200 3103         <https://www.jacobs-university.de/>

---

From: Christian Hopps <[email-masked]>
Date: Tue, 4 Jan 2022 10:23:39 -0500

> On Jan 4, 2022, at 6:26 AM, Jürgen Schönwälder <[email-masked]> wrote:
> 

100% agree.

The vast majority of the users of these YANG modules and models will probably never read the multitude of underlying RFCs. What they will do is interact with the sum of many modules that model these RFCS, maybe even using a single unified management system. I think consistency should be defined in that context then, from the users standpoint.

Thanks,
Chris.

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 4 Jan 2022 16:33:25 +0100

On 2022-01-04, at 12:26, Jürgen Schönwälder <[email-masked]> wrote:
> 
> tells a human operator over the phone

Indeed, a consistent convention wins.

The question was whether the consistency should be on the YANG side or on the side of each specific application modeled in YANG, and I think operationally we have a strong argument for the former (the poor applications people need to learn YANG anyway and they can learn that convention along the way).

By the way, hyphenation is something different (dividing a word to obtain a line break and inserting a hyphen); the word you are looking for is kebab-case [1].

Grüße, Carsten

[1]: https://en.wiktionary.org/wiki/kebab_case
(To maximize confusion, this link actually uses snake_case [2], duuh…)
[2]: https://en.wiktionary.org/wiki/snake_case

---

From: tom petch <[email-masked]>
Date: Tue, 4 Jan 2022 17:10:51 +0000

From: netmod <[email-masked]> on behalf of Carsten Bormann <[email-masked]>
Sent: 04 January 2022 15:33

<tp>
The OED defined hyphenation as meaning 'contains a hyphen' so I shall stay with that pro tem.

I prefer the absence of hyphens so I do not have to spell out their presence over the phone to the operator who is trying to restore their crashed payments system.  Case insensitivity helps in that regard as well.

Tom Petch
Grüße, Carsten

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 4 Jan 2022 18:31:39 +0100

> The OED defined hyphenation as meaning 'contains a hyphen' so I shall stay with that pro tem.

Which is a nice example for how general purpose dictionaries don’t always capture the full meaning of technical terms very well.
(Wikipedia is better here: https://en.wikipedia.org/wiki/Hyphenation redirects to https://en.wikipedia.org/wiki/Syllabification which explains:
“This article is about the division of words to break lines”.)

For many of us, a hyphenated “hyphenation" is “hy-phe-na-tion”, which is not what is meant here.  

(And, to add injury to insult, there actually is no hyphen in a kebab-case term, as the words are connected by a Unicode hyphen-minus U+002D, not a Unicode hyphen U+2010.  So you’d need to say hyphen-minus-ated...)

> I prefer the absence of hyphens so I do not have to spell out their presence over the phone to the operator who is trying to restore their crashed payments system.  

Soyoupreferforwordstoruninlikethis?
No, you need those word breaks, and “hyphen” is easy to say on the phone, or actually given that ASCII does not really have hyphens anyway, you can say “dash”, which is one syllable shorter.

> Case insensitivity helps in that regard as well.

Absence of frivolous case variation helps even more.

But all this is irrelevant; the YANG ecosystem’s preference for kebab-case is well-established; I just was pointing out the common term to use for identifying that convention.

Grüße, Carsten