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

["C. M. Heard" <heard@pobox.com>]

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.