[Xorp-hackers] Cli style guide draft

[Hasso Tepper]

Eddie Kohler wrote:
> 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.

I thought about that. At first I think that making exceptions is bad 
style - if to use it in command strings, then everywhere. But I don't see 
need for that. As general rule if user is going to change timers, he/she 
has to have exact knowledge what's he/she is doing and therefore has to 
know units as well. Mostly commands speak for theirselves - you wouldn't 
expect interpacket-delay specified in seconds? ;)

We also discussed with coworkers it and agreed that it's unnecessary - 
info in help is enough.

There are some cli's which are using msec rarely if they are moving timers 
from seconds to milliseconds - ie. there is old command "some-timer" and 
the new one "some-timer-msec". But most implementations just adjust value 
in such cases during upgrade (that's why it's good idea to have version 
info in the configuration file ;).

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

I don't think that it's good idea either. If, then only representation 
should have it - it would be really annoying to type sec/msec. And it 
introduces complexity in cli. And it would make value string in cli (at 
least for now) and it would make sanity checking much harder etc.


-- 
Hasso Tepper