[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

snmpconf comments should never include technical descriptions



>>>>> On Fri, 09 Mar 2001 09:25:33 -0500, Jon Saperia <saperia@jdscons.com> said:

Jon> Wes wrote:
>> >     I'd actually suggest a note be put into the -bcp document as well
>> >     describing that comments should never be used to describe
>> >     functionality of objects, but rather to mark things to remember, etc.
>> 
Jon> Wes, lets start a separate thread on this.

Ok, this is, then, a separate message on the subject.

Jon> I am not sure what you mean here. Please propose some text. One
Jon> thing is that I have always felt that the DESCRIPTION should
Jon> include information about the side effects of the behavior of the
Jon> object on the network. This is not what it was originally planned
Jon> for, but people have come (as you point out) to rely on the
Jon> DESCRIPTION clause for many different things.

IMHO, it is very bad practice to describe how an object or group of
objects is supposed to behave, why it is in existence, etc, outside of
the description clause for that object or group of objects.  Comments,
specifically, should never be used to document an object in any way.
Something like:



Proper and Improper use of MIB comments

  Comments within MIBs are started with two '-' symbols: "--".
  Comments are ignored by any tools which systematically parse a MIB
  definition in order to extract some set of information from it.
  Because of this, it is extremely important that comments not be used
  to describe how an object or group of objects is supposed to behave,
  why they exist.  More generally, comments should not be used as a
  form of documentation.  The proper place for documentation is in the
  DESCRIPTION clause of an appropriate object.

  Comments are not without merit, however.  They can be used to
  provide a separator between large sections of the mib, such as:

    --
    -- Begin Acme notification objects
    --

  They can also provide a place for MIB authors to comment on sections
  that need to be fixed, or to document problems with an object.
  Typically, though, these types of comments would be removed before
  external publication.

  In short, if you're unsure of where to put text, put it in a
  description clause not in a comment.



My point to Steve was that he was violating the first paragraph and
included a bunch of descriptive text describing what the object below
it was supposed to be.

Steve, you're 05 draft has cleaned this up to some extent and its'
much better, thanks.
-- 
Wes Hardaker
NAI Labs
Network Associates