[Xorp-hackers] Cli style guide draft

[Justin Fletcher]

> Agree. Also, I'd like to add the following:
> 
> * Node names may include digits, but their usage should be limited,
>   and should never be used as the first symbol.

Good addition.

> > * Existing commands are only changed after significant
> consideration.
> > 
> >   This will help preserve backwards compatibility of configuration
> files
> >   between releases.
> 
> This is not really a coding style, but more like a policy.
> Though, given there is no better place for it, maybe it should be
> added to the cli-style.txt document.

True - but putting it here gives it a little visibility :-)

> > * Help for high level configuration commands begin with "Configure
> <area>"
> > 
> >   Example: create protocols ?
> > 
> >   bgp             Configure BGP options
> 
> I prefer "BGP configuration" or "Configure BGP" or something
> similar, because "BGP options" may be ambiguous (i.e., it may have
> some protocol-specific meaning).
> FWIW, in JunOS the help strings at the protocol level are
> not consistent: some are "FOO options" while other are
> "FOO configuration" so we can choose the wording we like.

Yes, I've noticed the same about JunOS.  Maybe they don't have a
CLI style guide :-)

I'm perfectly happy with "Configure BGP" or "Configure RIP" or
"Configure RIP options" or something similar, as there is a consistent
appearance to high-level commands for a major system area.  It's likely
you can't fully specify a help string where you just fill in <area>, but
this will give a start.

> > * Help for area options describe the available parameters.
> > 
> >   Example: create protocols bgp ?
> > 
> >   local-as        Autonomous System (AS) number for this domain
> > 
> > * Help for specific parameter configuration commands identify the
> value to be
> >   configured.
> > 
> >   Example: create protocols bgp local-as ?
> > 
> >   local-as        Local AS number
> 
> Implementing something like the above two bullets would require
> associating two short help strings with each parameter, and I don't
> see the (significant) difference in the information they would
> provide.
> So I'd prefer there is a single short help string (as it is now).
> FYI, there is also a long help string that can be associated with
> each node, thought right now this string is not used (yet).

Whoops - I must not have been clear.  Two help strings wasn't the
intention - it's just a matter of making the help more and more
precise as more parameters to the command are added, as in the examples
for

create protocols ?
create protocols bgp ?
create protocols bgp local-as

Hmm - maybe that should simply say:

* Help strings should become more precise as additional parameters
  are specified.

> > * Protocol acronyms are listed in upper case in short help strings.
> > 
> >   For example, use BGP instead of bgp.
> 
> I would say that the protocol acronyms should follow the common
> convention: typically it is all upper (e.g., BGP), but sometimes it
> may include lower cases as well (e.g., VoIP).

Yup, yup.  How about:

* Protocol acronyms are listed using common conventions in short
  help strings, typically all upper case.

Justin Fletcher
Vyatta