# # $XORP: xorp/devnotes/cli-style.txt,v 1.5 2006/07/19 22:53:34 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 " 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).