[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