vimconf2016.md

Best practices for building Vim plugins

2016-11-05 VimConf 2016 thinca

About me

• thinca
  • Twitter: @thinca
  • GitHub: thinca
• I've been publishing many Vim plugins
  • quickrun.vim
  • ref.vim
  • themis.vim

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

2. Clear-cut namespace

• Functions are put in the namespace inevitably

function! very_cool#feature() abort
endfunction

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

Conclusion

• 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