RE: Naming Conventions for Descriptors (was: comments/review <draft-ietf-ops-mib-review-guidelines-00.txt>)

["Wijnen, Bert (Bert)" <bwijnen@lucent.com>]

Looks good to me

Thanks,
Bert 

> -----Original Message-----
> From: C. M. Heard [mailto:heard@pobox.com]
> Sent: woensdag 19 februari 2003 22:22
> To: Mreview (E-mail)
> Subject: Re: Naming Conventions for Descriptors (was: comments/review
> <draft-ietf-ops-mib-review-guidelines-00.txt>)
> 
> 
> On Fri, 7 Feb 2003, C. M. Heard wrote:
> > On Fri, 7 Feb 2003, Wijnen, Bert (Bert) wrote:
> > > I have one more concern. It is something I run into
> > > very often when reviewing MIB modules. And that is
> > > 
> > >    Naming Conventions for descriptors.
> > 
> > [ lots of good details snipped ]
> > 
> > > I think I would like it to also be one of the checkpoints in
> > > appendix A.
> > > 
> > > Do people find this to much of another CLR ??
> > 
> > Bert, I like this idea.  Organizationally, I would suggest
> > that it belongs somewhere at the end of 4.6 (it would be
> > 4.6.6 if we don't do any section renumbering).  And if you
> > want it mentioned in the checklist in Appendix A it seems
> > like item 10 is the place to mention it.
> 
> Well, since we decided to wait until the IANA MIB issues are
> resolved before I submit the -01 draft I had some time to think
> about naming conventions some more.  Here is a concrete proposal
> for incorporating some of Bert's ideas.  Because of the previous
> absence of vocal support, I have written up Bert's preferred naming
> conventions as a set non-binding suggestions (i.e., no capitalized
> imperatives from RFC 2119) to be included in a new appendix, with
> pointers in the main text at two strategic places.  Details follow
> below.  Please speak up if you object.
> 
> Thanks,
> 
> Mike
> 
> -- proposal starts here --
> 
> 1.) Change the last sentence in Section 4.1 from
> 
>    It is strongly RECOMMENDED that module names be mnemonic.
> 
> to
> 
>    It is RECOMMENDED that module names be mnemonic.  See Appendix E
>    for additional suggestions.
> 
> 2.) Rename Section 4.2 to "Descriptors, TC Names, and Labels".  In the
> first paragraph change "descriptors associated with macro invocations"
> to "descriptors and names associated with macro invocations";  in the
> second paragraph change "descriptors" to "descriptors and TC names".
> This is needed to make the terminology consistent with the usage in
> the SMI documents.  Then at the end add the following paragraph:
> 
>    See Appendix E for suggested descriptor and TC naming conventions.
> 
> 3.) Add the following appendix:
> 
> Appendix E:  Suggested Naming Conventions
> 
>    Authors and reviewers of IETF MIB modules have often found the
>    following naming conventions to be helpful in the past, and authors
>    of new IETF MIB modules are urged to consider following them.
> 
>    - The module name is typically of the form XXX-MIB, where XXX is a
>      unique prefix (usually all caps with hyphens for separators) that
>      that is not used by any existing IETF MIB module.
> 
>    - The descriptor associated with the MODULE-IDENTITY invocation is
>      typically of the form xxxMib or xxxMIB, where xxx is a mixed-case
>      version of XXX starting with a lower-case letter and without any
>      hyphens.
> 
>    - Other descriptors within the MIB module should start 
> with the same
>      prefix xxx, i.e., should be of the form xxxSomeOtherName.
> 
>    - Names of TCs that are specific to the MIB module and names of
>      SEQUENCE types that are used in conceptual table 
> definitions should
>      start with a prefix Xxx that is the same as xxx but with the
>      initial letter changed to upper case.
> 
>    - The descriptor associated with a conceptual table should 
> be of the
>      form xxxZzzTable;  the name of the SEQUENCE type for the
>      corresponding conceptual row should be of the form 
> XxxZzzEntry; the
>      descriptor associated with the corresponding conceptual 
> row should
>      be of the form xxxZzzEntry;  and the descriptors associated with
>      the subordinate columnar objects should be of the form
>      xxxZzzSomeotherName.  This makes it easy to see which objects are
>      parts of a given table.
> 
>    - When abbreviations are used, then they should be used 
> consistently.
>      Inconsistent usage such as
> 
>        xxxYyyDestAddr
>        xxxZzzDstAddr
> 
>      should be avoided.
> 
>