[Xorp-hackers] Cli style guide draft

Pavlin Radoslavov pavlin@icir.org
Thu, 20 Apr 2006 12:22:03 -0700


> I've a few proposed additions; 
> 
> * Node names are all lower-case characters.

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.

> * 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.

> * 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.

> * 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).

> * 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).

Pavlin