[Xorp-hackers] Cli style guide draft

[Justin Fletcher]

------=_Part_0_22449018.1145555252846
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 7bit

I've a few proposed additions; 

* Node names are all lower-case characters.

* Existing commands are only changed after significant consideration.

  This will help preserve backwards compatibility of configuration files
  between releases.

* Help for high level configuration commands begin with "Configure <area>"

  Example: create protocols ?

  bgp             Configure BGP options

* Help for area options describe the available parameters.

  Example: create protocols bgp ?

The changes are integrated into the attached version.

Justin Fletcher
Vyatta

  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

* Protocol acronyms are listed in upper case in short help strings.

  For example, use BGP instead of bgp.
------=_Part_0_22449018.1145555252846
Content-Type: text/plain
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename=cli-style.txt

#
# $XORP: xorp/devnotes/cli-style.txt,v 1.2 2006/04/19 05:59:32 pavlin Exp $
#

	Provisional XORP CLI coding style

This is a *provisional* attempt to lay down some rules that we can
adhere to when it comes to adding new CLI configuration statements or
commands (or modifying existing ones).

Note that each configuration node can have a "short" and a "long" help
string. In the text below we use the terms "short help string" and
"long help string" to differenciate between them.

* Each configuration node should have a short help string.

* A configuration node name SHOULD be less than 20 symbols long.
  The associated short help string SHOULD be less than 56 symbols long.
  The length of a configuration node name + its short help string
  MUST NOT exceed 76 symbols.

  This is to ensure that the output of possible completions would fit into 
  80 symbols wide terminal. In most of cases it's wrapping that makes the
  output look really bad.

  Both node names and short help strings should be concise. Node names
  are especially important. If it can be shortened below 20 symbols
  without loosing the point, it should be done. If it can't be done, OK,
  but these cases should be kept minimum. For example:

  restore-original-config-on-shutdown -> restore-system-conf
  enable-ip-router-alert-option-check -> router-alert-check

* If a node name is composed of more than one word, use '-' to separate
  the words. For example:

  multicastcapable -> multicast-capable

* Don't specify the units in the node names (e.g., sec or msec).
  This info should be in the short help string. For example:

  interpacket-delay-msecs  Minimum delay between outbound RIPng packets.
  vs.
  interpacket-delay    Minimum delay between outbound RIPng packets (msec)

* Node names are all lower-case characters.

* Existing commands are only changed after significant consideration.

  This will help preserve backwards compatibility of configuration files
  between releases.

* Help for high level configuration commands begin with "Configure <area>"

  Example: create protocols ?

  bgp             Configure BGP options

* 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

* Avoid "Set ...", "Edit ..." etc in the short help strings.

  A short help string should just describe the purpose of the particular
  variable or command. Using "Set" or "Edit" in the short help string
  can be logically wrong as well - variables and commands aren't always
  set, but sometimes deleted as well. For example:

  horizon    Set the horizon type applied to routes announced on  address.
  vs.
  horizon    Horizon type applied to announced routes

* Short help strings begin with capital letter and don't have a dot in
  the end.

  Just to make the look consistent.
 
* Protocol acronyms are listed in upper case in short help strings.

  For example, use BGP instead of bgp.

* Keep to minimum the number of parameters the user has to configure.

  For example, a timer with a jitter can be described as
  "some-timer-min" and "some-timer-max". If the user wants to change
  the timer value, he/she has to modify both parameters. Usually the
  user wants to modify only the average value of the timer.
  In this example, "some-timer" and "some-jitter" should be used instead,
  where "some-jitter" should have some reasonable default value (in
  percents rather than in absolute value).

* Commands should describe what they do, not what they can be used for.
  For example, the purpose of the following command is not very clear:

  accept-non-rip-requests  Answer RIP requests made from non-RIP processes

  It is better use following command and help string to describe it:

  source-port-check    Answer RIP requests made only from RIP port

  Additional details about the command can be provided in the user
  documentation.

------=_Part_0_22449018.1145555252846--