#
# $XORP: xorp/devnotes/cli-style.txt,v 1.4 2006/07/11 23:52:25 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.

* Node names should be all lower-case characters. They may include
  digits, but their usage should be limited, and should never be used as
  the first symbol.

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

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

* 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 most cases it is better to use percents rather than absolute value
  as jitter. Such decision should be done on case by case by taking into
  account the number of parameters that need to be modified under normal
  circumstances.

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

* The short help strings for each module (e.g., a protocol) should begin
  with "<Module> configuration".

  Example: set protocols ?

  rip                  RIP configuration

* The short help strings should become more precise as additional
  parameters are specified, and should not provide more information than
  necessary.

  Example: set protocols rip interface eth0 vif eth0 address 1.2.3.4
           authentication md5?

  md5                  MD5 authentication key

  Bad example for a help string:

  md5                  RIP MD5 authentication key on this interface/vif/address

* Protocol acronyms in help strings should use common conventions,
  typically all upper case.

  Example: BGP, RIP, RIPng, VoIP

* All timer-related configuration statements should follow common
  convention:

  - All configuration statements that represent periodic events should
    be named "foo-interval".

  - All configuration statements that represent expiration timeout
    events should be named "foo-timeout".

  - All configuration statements that represent lag/delay in events
    should be named "foo-delay".

  - All configuration statements that represent absolute time should be
    named "foo-time".

  In special cases a timer-related configuration statement might not
  follow the above convention, but there should be good justification
  for that (e.g., consistency with other router vendors, etc).

* In general, the naming convention of other router vendors should be
  used as a guideline when choosing the name of a configuration
  statement, unless there are good reasons to choose a different name.

* The name of an existing command should be changed only after careful
  considerations. The same applies for deleting a command or moving it
  to a different part of the configuration tree.

* If a command is changed (renamed, deleted or moved), the original
  command should be marked as "deprecated" (i.e., by using the
  "%deprecated" keyword in the rtrmgr template) and kept in the
  configuration tree for at least three major releases or 18 months
  (whichever comes later).

  For example, if a command is deprecated in Release-1.5, the deprecated
  state about that command can be removed in Release-1.8 (assuming there
  have been at least 18 months between those two releases).
