Subject: MIB Report 2/3: Coding Anomalies

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

------------------------------------------------------------
MIB Report 2/3: Coding Style Anomalies

I run a "lint" (i.e., coding style checking) over the latest
version of MPLS MIB drafts and generated a report.

    draft-ietf-mpls-bundle-mib-04.fmt
    draft-ietf-mpls-fastreroute-mib-01.fmt
    draft-ietf-mpls-ftn-mib-04.fmt
    draft-ietf-mpls-ldp-mib-09.fmt
    draft-ietf-mpls-lsr-mib-09.fmt
    draft-ietf-mpls-tc-mib-05.fmt
    draft-ietf-mpls-te-mib-09.fmt

9 coding style anomalies are detected.  (A small number, compared with
525 object types and 22 TCs in total.)

The anomalies fall in 2 categories.

1. ENUM value list started with zero (0).
   GUIDELINE: All ENUM value list should start from 1 and up.

2. Define Numeric range with INTEGER.
   GUIDELINE: All numeric range should be defined with
   Integer32 or Unsigned32.

These are not errors, but coding style anomalies.  See details below.

-- Rupert

#====================================================================
# Checking on Objects

MODULE=LINK-BUNDLING-MIB

MODULE=MPLS-FRR-MIB

WARNING: ENUM Starts with Zero (0)
  mplsFrrConstProtectionMethod
  INTEGER { oneToOneBackup (0), facilityBackup (1) }

WARNING: ENUM Starts with Zero (0)
  mplsFrrConstProtectionType
  INTEGER { linkProtection (0), nodeProtection (1) }

WARNING: ENUM Starts with Zero (0)
  mplsFrrDetourMerging
  INTEGER { none (0), protectedTunnel (1), detour(2) }

MODULE=MPLS-FTN-MIB

MODULE=MPLS-LDP-MIB

WARNING: ENUM Starts with Zero (0)
  mplsLdpEntityAtmMergeCap
  INTEGER { notSupported (0), vcMerge (2) }

WARNING: ENUM Starts with Zero (0)
  mplsLdpEntityAtmVcDirectionality
  INTEGER { bidirectional (0), unidirectional (1) }

WARNING: ENUM Starts with Zero (0)
  mplsLdpEntityFrMergeCap
  INTEGER { notSupported (0), supported (1) }

WARNING: ENUM Starts with Zero (0)
  mplsLdpEntityFrLength
  INTEGER { tenDlciBits (0), twentyThreeDlciBits (2) }

WARNING: ENUM Starts with Zero (0)
  mplsLdpEntityFrVcDirectionality
  INTEGER { bidirectional (0), unidirection (1) }

WARNING: ENUM Starts with Zero (0)
  mplsLdpFrSesLength
  INTEGER { tenDlciBits (0), twentyThreeDlciBits (2) }

MODULE=MPLS-LSR-MIB

MODULE=MPLS-TE-MIB

Total Warnings:    9

---

From: "Zhu, Rupert" <[email-masked]>
Date: Sun, 10 Nov 2002 14:45:15 -0600

Tom, Joan:

Thanks for the reply.

I agree that there is no "syntax violation",
but the issue I raised is "coding style violation".  An analogy below.

    ----------------
    In every software programming guideline, we would see instructions like

        "DO NOT use magic number in code, use symbolic constant instead."

    Using magic number (e.g., 24, 168) in C/C++/Java program would
    pass compilation perfectly.  But seasoned software managers won't
    allow it because it is a bad style.
    ----------------

As explained in my report 1/3, "ENUM starting from 1" is a good coding
style in MIB design.  Most existing IETF MIBs stick with this practice
pretty well.  However, I do think Joan made a good case in retaining
the same coding across protocol message and SNMP message.

In engineering world, every rule has an exception.  :-)

Regarding your point #2, you are right.

My first run of "lint" was over a set of earlier MPLS MIB drafts.
It generated 16 warnings on coding style violation.  Before posting,
I noticed the new release of MIB drafts and did a second run.

The total number of warnings dropped to 9 and the anomalies of second
case disappeared.  Apparently, MIB drafts are getting better.

BTW, I am reading the latest version of MPLS-TE-MIB.  I will
provide my comments soon.

Regards,

-- Rupert

> -----Original Message-----
> From: Thomas D. Nadeau [mailto:[email-masked]]
> Sent: Sunday, November 10, 2002 1:30 PM
> To: [email-masked]
> Cc: Zhu, Rupert; [email-masked]
> Subject: Re: MIB Report 2/3: Coding Anomalies
> 
> 
> 
>          Rupert,
> 
>          Two points inline.
> 
> >Hello Rupert,
> >
> >Thank you for the comments. Please see in-line.
> >
> >At 05:47 PM 11/8/02 -0600, Zhu, Rupert wrote:
> >This was due to SMIv1 but SMIv2 does allow 0.  Admittedly,
> >many MIB authors were concerned with backwards compatibility
> >issues and start enums at 1 where it makes sense to do so.
> >
> >In the LDP-MIB the reason that these enums start with 0 is because
> >the actual values sent on the wire for these values would be 0.
> >I didn't see any reason that there should be "extra" code in there
> >checking an enum and then re-interrupting the value to zero to
> >send on the wire.
> >
> >Thanks, Joan
> 
>          I concur with Joan.  SNMPv2 allows for enumerations
> to begin with 0, and thus there are no coding conventions
> being violated.
> 
>          I do not see any examples below of the use of
> INTEGER with a range; they all look like enumerations
> to me.
> 
>          --Tom
> 
> 
> > >
> Success is relative; the more success, the more relatives. -Anonymous
> 
> 
>