key mapping best practices

Question

I found that I frequently needed a command in INSERT mode to open a line above the cursor (what O does in NORMAL mode)

I put this in my .vimrc

inoremap ao <esc>O

It works well. I chose the key sequence ao because I rarely encounter a and o together (also I remember it as "above open").

This set me thinking if there are some best practices when coming up with such mappings.
I use Tim Pope's vim-unimpaired plugin and love his choice of keys (He says those are extracted out of his vimrc).

What are some best practices that I can follow to find good key sequences that my .vimrc will also be easy to use for someone else?

Answer 1

:help map-which-keys gives some information on the subject:

If you are going to map something, you will need to choose which key(s) to use
for the {lhs}.  You will have to avoid keys that are used for Vim commands,
otherwise you would not be able to use those commands anymore.  Here are a few
suggestions:
- Function keys <F2>, <F3>, etc..  Also the shifted function keys <S-F1>,
  <S-F2>, etc.  Note that <F1> is already used for the help command.
- Meta-keys (with the ALT key pressed).  Depending on your keyboard accented
  characters may be used as well. :map-alt-keys
- Use the '_' or ',' character and then any other character.  The "_" and ","
  commands do exist in Vim (see _ and ,), but you probably never use them.
- Use a key that is a synonym for another command.  For example: CTRL-P and
  CTRL-N.  Use an extra character to allow more mappings.
- The key defined by <Leader> and one or more other keys.  This is especially
  useful in scripts. mapleader

See the file "index" for keys that are not used and thus can be mapped without
losing any builtin function.  You can also use ":help {key}^D" to find out if
a key is used for some command.  ({key} is the specific key you want to find
out about, ^D is CTRL-D).

---

They suggest:

• function keys and shifted function keys <F1>, <S-F2>, ...
• Meta-keys (ALT + {key})
• _ or , + {keys}
• using keys that are synonyms for a same command as a namespace
  e.g. <C-N>, + and j all move the cursor down one line ; you only need one and probably only use j so <C-N> and + could be good candidates to build a {lhs} such as <C-N> + {key}
• <leader> + {keys}
• typing on the command line :help {key}^D
{key} is the {lhs} you would like to use for a mapping, and ^D is Ctrl+D

In the unimpaired plugin, [ and ] have been chosen as namespaces.
You could do the same, find some {key} (or sequence of keys like co) which is not used alone and use the latter as a namespace.

Then, as :h map-which-keys suggests, to avoid overriding a default Vim command, you could type :h {key}^D, to find out which commands begin with {key}.
For example, when typing :h [^D, you should see [c (a normal command to jump backwards to the previous start of a change in diff mode), but not [a neither [b.
So [a and [b could be used as the {lhs} of a mapping but not [c.

Answer 2

I was like you, trying to figure out a way to get a list of all available key bindings, which wouldn't override any preexisting function, and tried to write a plugin to get the info. It's not finished, and will probably never be.

By trying to find all the syntaxes which would produce "free" key sequences, I found way too many exceptions, and edge-cases where I wasn't sure whether a key sequence could be considered as free or not.

That being said, in case you're interested, you could have a look at it, it's on github.

It installs the custom command :FK. I haven't used it for a long time, but IIRC, it accepts some optional arguments:

:FK -nomapcheck    don't check whether the key sequences would override one of your
                   custom mapping, or cause lag (timeout)

:FK -noleader      don't suggest key sequences using the leader key

:FK -nospecial     don't suggest key sequences using special characters

:FK -mode normal   suggest key sequences for normal mode

Inside a freekeys buffer, it installs a few buffer-local mappings, which you can find by typing g?.

It's only (somewhat) good for normal mode. The other modes haven't been really considered.

Again, it's not finished, and the code is a mess, so I suggest you remove the plugin once you've read and copied the information in which you're interested.