1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
|
#
# $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).
|
