Programs user interface, arguments and warnings

[Julien Yann Dutheil]

Hi,

Here is another (too) long email that you most likely do not want to read, but to which I will later refer to when you will complain about some changes I made :D

Jokes apart, I have been thinking for some time that a major limitation to the Bio++ programs is their "user interface". It has become rather heavy with a lot of options which can (and certainly does) prevent the (new) user to get a quick grasp on the tools the programs offer. I am in favour of giving as much control to the user as possible, but I must admit it works against us in many cases.

The solution is in my opinion to provide sensible default values for such parameters, yet giving the advanced user the possibility to modify them. Globally the current Bio++ ApplicationTools does that, yet outputting a lot of confusing warnings.

I have started to (slightly) modify the ApplicationTools classes to cope with this issue. Many methods such as getStringParameter, getDoubleParameter, etc. now take as extra argument a "warning level" setting the importance of the argument: a low value will systematically display a warning if no value is provided, will a high value will almost never complain, the default value being fine in most cases. These warning levels are compared to a global warning threshold which specifies how much warnings the user wants to see.
The global threshold is set to 0 (only the most important warnings are displayed) but can be changed using the BppApplication class: all Bio++ programs now have an additional argument --warning:
bppml --warning=3 will display much more warnings.

I propose the following scale:
0: arguments should be specified by the user, default value is only a suggestion
1: arguments where the default value will fit most situations
2: in between, can be used for sub-arguments for instance
3: argument that can safely be ignored
4: for debugging purpose only, default value should be used.

I have tested this scheme on my program CoMap, and I'm so far rather happy with the result. I will extend it to other programs progressively. I also tend to think that a similar scheme could be applied to the "verbose" level, to control the amount of information displayed on the terminal.

From the developer side, these changes are not fully backward compatible because of the additional argument in some functions, but nothing too serious (I think).

Any comment welcome.

Cheers,

Julien.