[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Naming Conventions for Descriptors (was: comments/review<draft-ietf-ops-mib-review-guidelines-00.txt>)
On Thu, 20 Feb 2003, Juergen Schoenwaelder wrote:
> >>>>> C M Heard writes:
> : 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.
>
> Well, in many cases we end up with multiple modules for a given
> technology these days. So in fact, module names usually have the
> structure XXX-YYY-MIB where XXX should be helpful to identify the
> technology being modelled. Now, I do not suggest to put all this into
> the document - but right now, the text might mislead people to believe
> that module names are just XXXX-MIB and that everything before -MIB is
> to be used as a prefix, which I think is not what we generally do.
I'm not sure how to fix this or even whether you are actually asking
me to do so. So, I have not (yet) changed anything in response to
this comment.
> : - 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.
>
> See, it is unclear here whether xxx here still refers to XXX from the
> XXX-MIB example. Perhaps it is more helpful to point things out at a
> concrete example which we all like?
OK, I have reworked the proposal to use my favorite example.
Unfortunately that is still an Internet-Draft (albeit one that is
in IETF last call). If you have an equally good example that is
already published as an RFC let me know and I will use it instead.
//cmh
-- revised 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 should be of the form XXX-MIB, where XXX is a
unique prefix (usually all caps with hyphens for separators) that
is not used by any existing IETF MIB module. For example, the MIB
module for managing optical interfaces [OPTIF] uses the prefix
OPT-IF and has module name OPT-IF-MIB.
- The descriptor associated with the MODULE-IDENTITY invocation
should be of the form xxxMIB, xxxMib, or xxxMibModule, where xxx is
a mixed-case version of XXX starting with a lower-case letter and
without any hyphens. For example, the OPT-IF-MIB uses the prefix
optIf, and the descriptor associated with its MODULE-IDENTITY
invocation is optIfMibModule.
- Other descriptors within the MIB module should start with the same
prefix xxx. OPT-IF-MIB uses the prefix optIf for all descriptors.
- 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. OPT-IF-MIB uses the prefix
OptIf on the names of TCs and SEQUENCE types.
- The descriptor associated with a conceptual table should be of the
form xxxZzzTable; the descriptor associated with the corresponding
conceptual row should be of the form xxxZzzEntry; the name of the
associated SEQUENCE type should be of the form XxxZzzEntry; and
the descriptors associated with the subordinate columnar objects
should be of the form xxxZzzSomeotherName. An example from the
OPT-IF-MIB is the OTMn table. The descriptor of the table object
is optIfOTMnTable, the descriptor of the row object is
optIfOTMnEntry, the name of the associated SEQUENCE type is
OptIfOTMnEntry, and the descriptors of the columnar objects are
optIfOTMnOrder, optIfOTMnReduced, optIfOTMnBitRates,
optIfOTMnInterfaceType, optIfOTMnTcmMax, and optIfOTMnOpticalReach.
- When abbreviations are used, then they should be used consistently.
Inconsistent usage such as
xxxYyyDestAddr
xxxZzzDstAddr
should be avoided.
4.) Add the following informative reference:
[OPTIF] Lam, H., Stewart, M. and A. Huynh, "Definitions of Managed
Objects for the Optical Interface Type", work in progress
(currently <draft-ietf-atommib-opticalmib-08.txt>).
5.) Add the following item to the "NOTES TO RFC Editor" on the last page:
************************************************************
* NOTES TO RFC Editor (to be removed prior to publication) *
~ ~
~ ~
* 5.) The informative reference [OPTIF] points to a work *
* in progress <draft-ietf-atommib-opticalmib-08.txt> that *
* is currently in IETF last call. If that draft is *
* published as an RFC prior to or concurrently with this *
* document, please update that reference to point to the *
* published RFC and update the reference tag to match. *
* *
************************************************************