Google has a style guide here:

• "casual" version
• hardcore version

And https://github.com/google/vim-maktaba is an excellent demonstration of those practices (I believe they even use the "docstrings" to generate their API documentation: https://github.com/google/vim-maktaba/blob/master/doc/maktaba.txt

We could adapt Google's style guide as needed. Rule of thumb: study netrw, then do the opposite :)

Yeah, the docstrings are generated by vimdoc. It's still a bit unstable:

Vimdoc is unstable. It's a collection of regexes and hacks masquerading as a complete vim documentation tool. But it works, and it's useful, and it will continue to be useful while it gets cleaned up.

But it's still nicer than managing your help files manually.

@Soares @dbarnett Is there a place to file issues on the style guide? There's a small mistake here: http://google-styleguide.googlecode.com/svn/trunk/vimscriptfull.xml#Forbidden_Commands

addmatch should be matchadd.

https://code.google.com/p/google-styleguide/ would be the place, but for some reason they don't have issue tracking enabled there. I guess they don't want your input about what should be in the style guide. ;)

I can update it. Thanks for pointing that out.

@dbarnett They also have incomplete reasoning about why not to use :echoerr: I have banned it not because it prints context (this may actually be good idea), but because you never know whether or not code after echoerr will be executed (:echoerr inside :try is an exception which breaks execution, outside it is an error which continues). The only two ways to resolve the issue are using :try around :echoerr (so that :echoerr will throw always) and not using :echoerr at all. You may also try to write code so that code after :echoerr may be executed or may be not executed without problems in any case, but the set of small rules for each dark VimL corner is high enough to create and follow “always …” and “never …” unconditional rules just to reduce cognitive load. Especially given that the first case may be replaced with throw (with some increase in error message length) and that with echoerr buried deep inside call graph controlling which code is subject to skipping due to echoerr transformed into exception is hard (actually problem is with code that is to be put inside finally section, but I do not think you can bet that you’ve written finally everywhere it is necessary).

BTW, as one of the maintainers of Google's vimscript style guide, I'd be interested in extracting the "how to not shoot yourself in the foot" parts to a set of canonical best practices to be widely shared. I'm more interested in broad adoption (by the set of plugin authors that write the plugins I use) than deep adoption (following every rule to the letter in repositories I own).

I'm not sure where a good home for this would be. http://vim.wikia.com/ is a little too collaborative if we want to publish standards instead of just collecting opinions.

FYI, I also found https://github.com/noahfrederick/vim-scripting-style-guide.

Even more important than a bunch of documentation would be a lint tool to detect violations. I found several "vimlint" projects and supposedly one is supported by syntastic, but couldn't figure out how to run them and they didn't look very high-quality.

https://github.com/Kuniwak/vint is a new vimscript linter that so far has produced good results for me.

@dbarnett

I think it is good idea to save my replies in gitter here:

ZyX-I When writing shada.vim set of files I looked at maktaba source and did something similar. But documentation in runtime/doc was not generated, I also treated such comments as “doxygen for VimL” (i.e. source code documentation for developers, not user documentation).

ZyX-I l: prefix is a thing I never followed, it makes code less readable and if you can make linter check that you are not omitting g: prefix (outside of functions) this does not make much sense either.

ZyX-I Basically the only argument for this I know is that you will not accidentally use global scope instead (which is actually likely should you e.g. write cycles to initialize some global variable). Interesting, this argument is not listed in Google style guide, while there are four more subjectable ones (“good practice”: it is you saying good, not me; “help remember about scope”: your code will not work if you forget this; “predefined variables”: there are five (search for VV_COMPAT), they are there for historical reasons (“…COMPAT”: Vi compatibility) and nobody is planning on adding any more (and I have only ever hit two of them: count and version)).

ZyX-I Also don’t think that using scope will prevent you from hitting some kind of predefined variables: there is b:changedtick, but there is no b:['changedtick']: it is the kind of predefined variable which internally is not even kept in any scope at all, there are only some checks here and there like “b:changedtick? do this: do else”.

Though I am wrong about Vi compatibility, vi does not have +eval. It is compatibility with previous versions that did not have v: to store such variables in.

thanks for the link，vim-maktaba is what I need.

For new runtime code, :help dev-lua is where patterns/practices are documented. And style is defined by the lintlua build target.

Don't need a Vimscript style guide because most Nvim-owned runtime files are in Lua.