Subject: MIB Report 1/3: About Coding Convention

From: "Zhu, Rupert" <[email-masked]>
Date: Fri, 8 Nov 2002 17:28:46 -0600

Dear MPLS MIB Authors:

I read through the latest version of MPLS MIB drafts.
Some of my findings are recorded in this and next two Emails.

This Email talks about coding styles in MIB design.  Next two Emails
bring up a style anomaly issue and a MIB structural issue, respectively.

----------------------------------------
MIB Report 1/3: About Coding Style

Similar to conventional programming, coding style of MIB object syntax
may affect the overall quality of a MIB definition.
For those companies that do automated code generation
directly from MIB definition file, the MIB coding style
becomes an issue.

The following are two simple guidelines (or best practices) that
are often overlooked by MIB authors.

1. DO NOT assign 0 (zero) to any valid ENUM element.
   ENUM value list should always start from 1.

   RATIONALE:  A piece of fresh memory may carry all zeros.  Engineers
   often erase a something by writing with all zeros.  When a variable
   has value 0, it's hard to tell whether this 0 is accidentally
   carried over or intentionally assigned.  (Ambiguity!)

2. DO NOT over-use INTEGER type.  Since SMIv2, INTEGER is mainly
   for ENUM definition.  Use more specific SMIv2 data types for all
   other scenarios.  (E.g., BITS, Integer32, Unsigned32,
   Counter32, Gauge32, etc.)

   RATIONALE: Using distinctive and precise data types enables authors
   to specify intended usage in an accurate and machine-readable fashion.
   It enhances readability and helps in automated code generation.
   (E.g., generate C++/Java programs.)

   Consisistency, Clarity, Readability.

To date, most published MIB definitions (in RFCs) are in good style.
The MIBs in Internet Draft stage tend to contain violations of
the best practice described above.

-- Rupert

Rupert Zhu
System Engineering
Santera Systems Inc
3605 E. Plano Parkway
Plano, TX 75074
Phone: 972-461-6383