[Xorp-hackers] Cli style guide draft

Eddie Kohler kohler@cs.ucla.edu
Sat, 15 Apr 2006 07:03:49 -0700


Hasso,

I think this is a very strong proposal!

One comment in terms of usability.  While I agree that getting rid of units 
from node names, it becomes problematic when different nodes with the same 
nominal unit (like time) have different scales (msec vs. sec).  That kind of 
thing is extremely easy to forget, and will really bite people.  I'm thinking of

interpacket-delay    ... (msec)
request-interval     ... (sec)
triggered-timer-max  ... (sec)
triggered-timer-min  ... (sec)
....

If interpacket-delay is the only one in msec, maybe it SHOULD take -msec in 
the node name to make that explicit.

But there is a better answer, which is to introduce types for time in seconds 
and time in milliseconds and allow people to actually enter unit suffixes, as 
in "set ... interpacket-delay 100msec".  FWIW, Click time units are now 
entered this way; it was a really good change.

Eddie


Hasso Tepper wrote:
> As I promised, here are my ideas about cli style guide. Feel free to 
> comment, make additions etc.
> 
> **************
> 
> * Configuration commands (node names) SHOULD be less than 20 symbols  
>   long. The length of configuration command + short help 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.
> 
>   So, keep the length of node names and short help minimum. 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
> 
> * No units in node names (sec, msec), this info should be in short help.
>   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 short help strings.
> 
>   Short help string should just describe shortly variables/commands. And 
>   note that it 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 dot in the 
>   end.
> 
>   Just to make the look consistent.
> 
> * Keep parameters user have to configure minimum.
> 
>   For example timers with jitter can be described as "some-timer-min" 
>   and "some-timer-max" (as it is in rip(ng)). If user wants to change 
>   timer, he/she has to configure two parameters. But mostly it's just 
>   average value which user wants to change. So, prefer "some-timer" 
>   and "some-jitter" with good default to jitter, better in percents than 
>   in absolute value.
> 
> * Commands should describe what they do, not for what they can be used.
> 
>   For example there is command in rip(ng):
> 
>   accept-non-rip-requests  Answer RIP requests made from non-RIP processes
> 
>   It's not clear at all what it does. Better use following command and 
>   help and describe for what it can be used in documentation: 
> 
>   source-port-check    Answer RIPng requests made only from RIPng port
> 
> 
> **************
> 
> I played with these ideas in RIPng configuration and picture (to make sure 
> that mail clients don't mess result with wrapping) with result is 
> attached.
> 
> 
> regards,
> 
> 
> 
> ------------------------------------------------------------------------
>