index edit log

designing a vim plugin

Note: Vim 7.4 will have improved python support. So this file should be updated also telling about how to write the perfect Python plugin.

This is my (Marc Weber's) recommendation:

Why are you writing the plugin ?

Maybe it does already exist? finding-a-vim-plugin.

Make yourself aware about why you want to write it - and document this in the README file or doc/*.txt files, so that others can decide on using your plugin fast.

python/ruby/.. support

See vim-scripting

files belonging to a Vim plugin

plugin/*.vim files: Put the user interface there and code required to configure the plugin as well as code which is loaded always anyway

autoload/*.vim files: Put code which is loaded sometimes only to keep startup time fast

configuration

Since Vim 7 there are dictionaries, so we can use them. I personally like binding a global dictionary to a buffer local variable like this:

if !exists('g:your_plugin_name') | let g:your_plugin_name = {} | endif | let s:c = g:your_plugin_name
let s:c.enable_feature_x = get(s:c, 'enable_feature_x', default_value)
let s:c.command_x_lhs = '\foo'
...

exec 'noremap '.s:c.command_x_lhs.' :call dosomething()<cr>'

Its nice because the user can override any settings this way:

let g:your_plugin_name = {}
let g:your_plugin_name.enable_feature_x = 1
let g:your_plugin_name.command_x_lhs = '\bar'

and everything belonging to that plugin can be put into the dictionary which can be accessed from everywhere. (config, caches, etc)

plugin dependencies

VAM (vim-addon-manager) introduced a addon-info.json file which let's you specify dependencies. Using VAM they'll be installed automatically.

enough, just show me a small example

vim-addon-commenting which is minimal, separates user interface and implementation.

completions

Well - hot topic. Sometimes you may want to have multiple completion implementations at the same time. My personal recommendation is bind them all to different keys so that you always know exactly what your completing. vim-addon-completion has some helper functions

documenting source

vimdoc generates documentation if you don't want to write help files entirely by hand.

Keep in mind that having too much documentation can take more time than it adds value. Thus think twice about what and how to document your code. Good code doesn't require much documentation.

test suite?

Example magnum

TODO

.gitattributes -> force LF line endings (document this) - some git distributions use 1310 when checking out files Vim has trouble with