consistent style for our public API add_domain()

[nancycollins]

Use case

our current user-facing API for adding a domain from a file in model_mod requires all the items to be collected into arrays and all be passed in together in the same call. most other user-facing API calls in dart are single-item with only one or two arguments, and less frequently requiring arrays of values. the version of add_domain() that doesn't use an input file has some of this flavor, adding sizes after the first call defines the variables.

Is your feature request related to a problem?

a consistent programming style is easier for users to use correctly, and easier for us to support. requiring many arguments in the same call means the user code has to assemble them first before making the call. this leads to more error-prone code and more complex logic.

Describe your preferred solution

the dart programming style, for most things, uses multiple single-purpose routines. e.g. get_obs_def_error_variance(), get_obs_def_time(), get_obs_def_type_of_obs(), etc. the argument lists are short, and reading the name of the routine makes the purpose of the call clear. the code that implements these routines are also short, and easier to debug.

an alternative programming style is 'all-in-one' routines where you have something like: get_obs_def_info() and you rely on the names of the arguments (which don't have to be helpful since they are supplied by the user) to intuit what is being asked for or set. either can be supported, but picking one and sticking to it gives a more coherent interface to our code.

the current add_domain() call is complex, and adding additional optional arguments to it just increases the complexity. an alternative strategy is to make a set of routines to add variables to a domain one at a time, in a loop, with separate calls to set the optional items like allowed min/max, and future needs like units or anamorphosis type. i believe this leads to clearer, easier to maintain code.

internally we have routines that also suffer from this complexity - e.g. setting arrays of lists of input/output filenames for domains.

Describe any alternatives you have considered

we can keep adding optional arguments to the existing add_domain() call, but as additional info is needed by the state structure and/or the i/o code, that might be a logical place to rethink this and add simpler routines. the existing add_domain() call may have to stay for backwards compatibility, but adding simpler alternatives allows new code to use a better programming strategy.

[hkershaw-brown]

the dart programming style, for most things, uses multiple single-purpose routines.

questionable.