octave-maintainers
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: HID design and function names


From: Daniel J Sebald
Subject: Re: HID design and function names
Date: Thu, 27 Jun 2013 13:01:07 -0500
User-agent: Mozilla/5.0 (X11; U; Linux x86_64; en-US; rv:1.9.2.24) Gecko/20111108 Fedora/3.1.16-1.fc14 Thunderbird/3.1.16

On 06/27/2013 12:35 PM, Rik 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?

I like it. The taxonomic approach is how I tend to organize file system directories as well, i.e., main concept first. If some of these items could be put into option form, that might be nice as well, e.g.,

jit ("enable")
jit ("disable")
jit ("enable", "local")
jit ("debug")
jit ("nodebug")

Dan


reply via email to

[Prev in Thread] Current Thread [Next in Thread]