Re: HID design and function names

[Juan Pablo Carbajal]

On Thu, Jun 27, 2013 at 7:35 PM, Rik <address@hidden> wrote:
> 6/23/13
>
> I was reading a book on good design principles and I think we could make
> things easier on our human users if we renamed some functions.
>
> It is probably easiest to show what I want by example.  A while ago we
> added ccquad which does Clenshaw-Curtis quadrature.  The difficulty is that
> every other quadrature routine begins with the prefix 'quad'.  There is
> 'quad', 'quadv', 'quadl', 'quadgk', and 'quad_options'.  Even with seealso
> links in the documentation the routine was likely to be missed.  To make
> things easier on users, the routine was renamed to 'quadcc'.  Now the
> 'quad' prefix is back to being the root of a family of functions.  This
> seems to fit well with human cognition which likes to bin things together
> under a perceived commonality.  It also works well in the Octave
> interpreter because typing 'quad<TAB>' produces a list of all the
> integration functions.  This is easier, even, than typing 'help quad' and
> inspecting the seealso links.
>
> So I would like to nominate a few other routines for re-naming.
>
> First, enable_jit_compiler and enable_jit_debugger are rather awkward.  The
> concept is the JIT compiler and I think people would think of that before
> they would think of searching under the word enable.  I would propose
> renaming "enable_jit_compiler" to "jit_enable".  For debugging, we already
> have families of functions under the "debug_" prefix such as "debug_java"
> and "debug_on_error".  I propose renaming "enable_jit_debugging" to
> "debug_jit".
>
> I also propose renaming "default_save_options" to "save_default_options".
> Again, default is not a word that you would think of when looking for
> commands related to save().  In addition, we already have functions such as
> "save_precision" and "save_header_format_string" which are organized using
> the "save" prefix.
>
> "saving_history" could be renamed to "history_saving" or 
> 'history_save_enable".
>
> A second tier of renamings:
>
> I think "gen_doc_cache" could plausibly be renamed "doc_cache_create" so
> that it would share the same root as "doc_cache_file".
>
> The get_ family of help routines (get_first_help_sentence get_help_text
> get_help_text_from_file) might be renamed to start with 'help_'.  Also,
> "suppress_verbose_help_message" would be easier to find if it started with
> 'help_'.
>
> The readline functions would probably be easier to find if they begin with
> the keyword readline (read_readline_init_file, re_read_readline_init_file).
>
> What do people think of this idea?
>
> --Rik
>

You have 100% of my support. If you need to build a team to do the
changes, do let me know.