Many plugins provide either user functionality (commands, autocommands, etc) or an API (of autoloaded functions) but not both. This separation is encouraged, as it allows other plugins to pull in a library without also pulling in commands, setting changes, and other plugin functionality that affects the end user.

• Use maktaba flags for plugin configuration. Users can configure them using the :Glaive command.
• Check if configuration variables exist before setting them. if !exists('g:myplugin_option') let g:myplugin_option = 1 endif

Provide help files generated by vimdoc. Write documentation in .vim files in conformance with the vimdoc standards and include fields like "description" and "author" in the addon-info.json file (see the VAM documentation).

• Use two spaces for indents.
• Do not use tabs.
• Use spaces around operators except for arguments to commands.
  • Using spaces around operators for commands is often invalid syntax. This is inconsistently enforced by vimscript. To be safe, always omit whitespace around arguments to commands.
  • let s:variable = "concatenated " . "strings" command -range=% MyCommand let s:variable="concatenated "."strings" command -range = % MyCommand
• Do not introduce trailing whitespace.
  • You need not go out of your way to remove it.
• Restrict lines to 80 columns wide.
• Indent continued lines by two tabs (four spaces).
• Do not waste whitespace aligning common segments of similar commands. It is both difficult and expensive to maintain.
  • command -bang MyCommand call myplugin#foo() command MyCommand2 call myplugin#bar() command -bang MyCommand call myplugin#foo() command MyCommand2 call myplugin#bar()

• variable_names_like_this
  • FuncRef variables count as functions and should be named like functions.
  • This (pathological) convention is enforced by vim itself.
• Prefix global variables with g:
  • Vimscript allows you to create global variables without prefixing them.
  • It is very bad practice to introduce non-prefixed global variables into scope.
  • Global variables should only be used for plugin configuration.
  • This does not apply to functions defined in autoload directories.
• Prefix script-local variables with s:
  • This prevents namespace collisions between plugins.
  • This also applies to script-local functions.
• Prefix function arguments with a:
  • This is enforced by vim itself.
• Prefix function-local variables with l:
  • This is not enforced by vimscript but is good practice.
  • It helps you remember that all other variables must be prefixed with scope.
  • l: disambiguates between function-local and vim-predefined variables. For example, count refers to v:count, not l:count.
  • It future proofs your scripts against the introduction of new vim-predefined variables.
• Prefix pre-defined vim variables with v:
  • This is not enforced by vimscript but is good practice.
  • It provides context as to where the (undeclared) variable is coming from.
  • It reminds you that the variable can not be assigned to.
• Prefix buffer-local variables with b:
  • This is useful for plugins that keep per-buffer state.

Prefer single quoted strings. Specifically, in order of precedence:

• Always use single quotes for regular expressions.
  • '\s*' is not the same as "\s*"
  • Single quotes will prevent the need for excessive backslashes.
  • Double single quotes escape to one single quote in single quoted strings: 'example ('')' represents the string example (')
• If your string requires escape characters (\n, \t, etc.) use double quotes.
  • Escapes can not be expressed in single quoted strings.
  • Remember that '\n' in a regex does not represent a newline, but rather "\n". You only need to use double quotes when you want to embed the represented character itself (e.g. a newline) in the string.
• If your string contains no escapes nor single quotes, use single quoted strings.
  • Most strings in vimscript are regexes, so this provides maximum consistency.
• If your non-regex string contains single quotes but no double quotes, use double quotes.
  • Don't bother escaping strings if you don't have to.
  • This is similar to the python string rules.
• If your string contains both single and double quotes, use whichever quoting style requires less escaping.
  • Break ties in favor of single quotes.

• Prefer long names of built in settings (i.e. tabstop over ts).
• Set local settings unless you explicitly want to set global settings.
  • Use setlocal and &l: instead of set and &.

• CommandNamesLikeThis
• Commands should be defined in one block with no whitespace between them.
  • Name commands semantically at the expense of a common prefix.
  • command WhitespaceFixTrailing command WhitespaceFixIndentation command FixTrailingWhitespace command FixIndentation
• Use command without a bang.
  • This notifies users to command name conflicts immediately at startup.
  • Command name collisions are an error and should not fail silently.
  • Plugins are guarded against re-entry, so a single vim session should never attempt to re-define defined commands.
• Do not put logic in commands.
  • Delegate to functions instead.
  • Pass non-argument command parameters (<bang>, <register>, etc.) before argument parameters (<f-args>, etc.).
  • Otherwise variable-length argument functions are difficult to implement.
• Do not autoload commands.
  • Autoloaded commands will not be available until after a function in the same file is called.
  • Commands intended to be used in the .vimrc should be defined in a instant/commands.vim file in plugins using maktaba, or explicitly installed via an autoload function in non-maktaba plugins.

• All autocommands should be defined in the plugin/autocmds.vim file.
  • This allows users to disable your autocommands with Glaive myplugin !plugin[autocmds].
• Declare all autocommands in an augroup block.
  • This allows your autocommands to be cleared with autocmd!.
  • If your plugin only has one augroup, the augroup name should be the same as your plugin name, with underscores in place of any hyphens.
  • Otherwise augroup names should start with your plugin name followed by an underscore.
• Do not put logic in autocommands.
  • Delegate to functions instead.
• When creating a new augroup, clear it with autocmd!
  • This allows your plugins to be re-enterable.

• FunctionNamesLikeThis
• Prefix all script-local functions with s:
• Do not provide global functions. Use autoloaded functions instead.
• Place two blank lines between top-level functions.
• Declare all functions with abort.
  • If you do not do this, the function's behavior depends upon whether it is called within a try..endtry block somewhere on the stack.
  • The abort keyword forces the function to act consistently.
  • Without it, the function may (or may not) attempt to continue execution after an error occurs.
• Use function! with a bang.
  • This allows developers to re-source their scripts and have the functions reloaded without complaint.
  • Function names should never collide because functions should always be either script-local or defined in an autoload directory.
  • Failing to use a bang in any function in an autoload file will lead to cryptic errors if vim tries to re-source the file (e.g., if you refer to an nonexistent autoload function).
• Use ... for optional arguments, not for lists of arguments.
  • Vimscript functions take at most 20 arguments.
  • Lists have no such length restriction.
  • Your function is likely to break when given too many arguments if you use ... for a list of arguments.
• Throw exceptions rather than printing errors.
  • Printed errors can not be caught.
  • Top-level functions expecting errors may catch them and print error messages, but even those should throw their own errors when they choke.

• Define key mappings in plugin/mappings.vim, using maktaba#plugin#MapPrefix to get a prefix.
  • Mappings defined in the special plugin/mappings.vim file will be disabled by default (by the standard maktaba#plugin#Enter() boilerplate).
  • Users can enable key mappings with Glaive myplugin plugin[mappings].
• Make all mappings with <unique>.
  • This will inform the user when they have a mapping conflict instead of silently clobbering their existing mappings.
• You may provide pseudo-mappings using <Plug> and your plugin's name in plugin/plugs.vim (separate from standard key mappings).
  • <Plug> is a sequence which can not be typed.
  • You can do something like noremap <Plug>namespace#MappingName some_key_sequence and then users can do noremap <leader>x <Plug>namespace#MappingName to take advantage of your pseudo-mapping.
  • Pseudo-mappings should not be in plugin/mappings.vim or they will be disabled by default.
  • Such pseudo-mappings should be named <Plug> followed by your plugin name, a pound sign, and a unique mapping name (CamelCased like a function).
• Always use the noremap family of commands. Never use the map family.
  • map depends upon the user's existing mappings, and could do anything.
• Only use noremap for commands that both make a motion and take a range.
  • noremap makes mappings in normal, visual, and operator-pending modes.
  • If you don't want all these use nnoremap onoremap or vnoremap explicitly.
• Always use <SID> in place of s: when accessing script locals in mappings.
  • Using s: will often fail as the mapping attempts to type a literal s and colon.

Declaring dependencies in addon-info.json allows conformant plugin managers (like VAM) to ensure dependencies are installed. See the VAM documentation for details.

Calling maktaba#library#Require from dependent code at runtime ensures that dependencies have been installed and that they don't include unsafe non-library files.

Following is a convention for exposing statusline flags to the user. A plugin should never modify the user's statusline except for when that is the only purpose of the plugin (powerline, etc.).

• Provide the Info, Alert, Warning, and Error functions under the <plugin-name>#status namespace.
• Info should provide information about the state of the buffer.
  • Example: The current git branch.
• Alert should provide a quiet reminder that the buffer is non-standard.
  • Example: The readonly setting is on.
• Warning should provide a warning about the current state of the buffer.
  • Example: The file has been edited elsewhere.
• Error should bring to attention a loud issue with the buffer.
  • Example: The file does not pass the syntax checker.
• By following these conventions, users can easily build up their own statusline customizing the verbosity and colors to their tastes.
• All functions should take no arguments and should return either empty strings or strings enclosed by square brackets, e.g. [Google]. For example:
  • A trailing whitespace plugin might return [$] if the file contains trailing whitespace
  • A prose writing plugin might return [write] if vim is in writing mode.
• Consider providing the <plugin-name>#status#Status function.
  • It should return the first non-empty of Error, Warning, Alert, or Info.
  • This is useful for users who want only the most relevant flag and do not have a colored statusline.

When compatible is set, many vim features are not available. The vim feature which most commonly affects vimscript authors is line continuations.

If you want your plugin to work in vim with vi compatibility on, you will need to save the compatibility options at the beginning of each plugin file, clear them, and restore them at the end of each plugin file. See :help use-cpo-save for details.

Plugins that depend on maktaba generally don't need to worry about compatible mode since maktaba currently just disables it, printing a warning.