Skip to content

Instantly share code, notes, and snippets.

What would you like to do?

Best practices for building Vim plugins

2016-11-05 VimConf 2016 thinca

About me

Today's Theme

  • There are many Vim plugins in the World

  • However, many plugins have problem

  • This session teaches the tips to build a better Vim plugin

Write help document

  • Documentation is culture of Vim

    • :help design-documented
    • This should also apply to plugin
  • README is not enough

    • It isn't possible to read from the inside in Vim

Be conscious of namespace

  • All plugins work on the same environment

  • UI you provide may conflict with other plugins

    • Ex commands
    • Key mappings
    • Functions
    • Variables
  • These namespaces do NOT belong to you!

Use plugin name for prefix

When your plugin name is very_cool.vim:

  • OK: :VeryCoolFeature :VeryCoolAction

  • NG: :VCFeature :ActionVeryCool

  • User can define shortcut when they feel "command is too long"

How is collision of the name avoided?

  • Unfortunately, there are no ways to avoid perfectly

  • Googling of a candidate of your new plugin name before you decide it

Be careful of interface especially

  • Environment of each interface is shared in Vim

    • if_python if_ruby if_perl if_lua ...
  • When you defined a global class/function in these interfaces, other plugin would also be affected

  • Also use appropriate namespace in these interfaces

Use autoload

  • Users install many plugins

  • Does your plugin make Vim's startup slow?

  • plugin/xxx.vim is loaded at startup of Vim

    • When this is heavy, a start of Vim becomes slow

Move main codes to autoload

  • plugin/xxx.vim defines UI only

    • Ex commands
    • Key mappings
    • Auto commands
  • These calls autoload function

Two purposes of autoload

  1. Lazy loading of the Vim script
  • This makes Vim's startup fast
  • Don't load autoload at startup of Vim
  1. Clear-cut namespace
  • Functions are put in the namespace inevitably
function! very_cool#feature() abort

Customizable by global variables

  • Vim plugin users like customization

    • So they use plugins
    • :help design-flexible
  • To provide option is a good idea

    • Using a global variable is good way for this
  • You don't have to do excessively

Global variables can put on autoload

  • This has clear-cut namespace

  • User can read a default value if it is needed

    • However, can't benefit from lazy loading
let g:very_cool#useful_config = 1

Provide key-mappings

  • Do not use global variable to provide key-mappings configuration

    • The user can assign only 1 trigger key
  • <Plug> can provide more flexible

nnoremap <silent> <Plug>(very_cool-action)
\                 :call very_cool#action()<CR>

Plugin original buffer is useful

  • You can provide original buffer from plugin

    • Use BufReadCmd and BufWriteCmd
    • Use form like {plugin-name}://...
      • :// is handled and specialized by Vim
  • :new and :put is not that good

    • This can not open by other way

Care about the scope

  • Many things has the scope

    • Variables
    • Options
    • Key mappings
    • Auto commands
  • Use buffer-local in original buffer

Provide natural key-mappings

  • Vim has builtin key mappings

    • E.g. w b e = Move the cursor
  • Do not make the mapping which isn't intuitive

    • User would be confused
  • Use <Leader> or <LocalLeader> for original feature

Open API

  • Combination is beautiful

  • You should provide API function to user and other plugins if you can

  • When you can't determine, provide function version of Ex command

Work on multi platform

  • Vim works on multi platform

    • :help design-multi-platform
  • If your plugin works on multi-platform, users become happy

  • To write a test would be helpful to you

Do not abbreviate commands and options

  • Shortcut version is provided for interactive use

  • Do not use these at script file


  • Introduced many tips for building Vim plugins

  • I wish that good Vim plugins increase by all over the world

  • I'm happy if this document helps it

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.