Skip to content

Instantly share code, notes, and snippets.

Created November 5, 2016 09:19
Show Gist options
  • Save thinca/785171e327e66c48d2d293690dc2f65a to your computer and use it in GitHub Desktop.
Save thinca/785171e327e66c48d2d293690dc2f65a to your computer and use it in GitHub Desktop.

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