Note: Vim 7.4 will have improved python support. So this file should be updated also telling about how to write the perfect Python plugin.
This is my (Marc Weber's) recommendation:
Maybe it does already exist? finding-a-vim-plugin.
Make yourself aware about why you want to write it - and document this in the README file or doc/*.txt files, so that others can decide on using your plugin fast.
See vim-scripting
plugin/*.vim files: Put the user interface there and code required to configure the plugin as well as code which is loaded always anyway
autoload/*.vim files: Put code which is loaded sometimes only to keep startup time fast
Since Vim 7 there are dictionaries, so we can use them. I personally like binding a global dictionary to a buffer local variable like this:
if !exists('g:your_plugin_name') | let g:your_plugin_name = {} | endif | let s:c = g:your_plugin_name
let s:c.enable_feature_x = get(s:c, 'enable_feature_x', default_value)
let s:c.command_x_lhs = '\foo'
...
exec 'noremap '.s:c.command_x_lhs.' :call dosomething()<cr>'
Its nice because the user can override any settings this way:
let g:your_plugin_name = {}
let g:your_plugin_name.enable_feature_x = 1
let g:your_plugin_name.command_x_lhs = '\bar'
and everything belonging to that plugin can be put into the dictionary which can be accessed from everywhere. (config, caches, etc)
VAM (vim-addon-manager) introduced a addon-info.json file which let's you specify dependencies. Using VAM they'll be installed automatically.
vim-addon-commenting which is minimal, separates user interface and implementation.
Well - hot topic. Sometimes you may want to have multiple completion implementations at the same time. My personal recommendation is bind them all to different keys so that you always know exactly what your completing. vim-addon-completion has some helper functions
vimdoc generates documentation if you don't want to write help files entirely by hand.
Keep in mind that having too much documentation can take more time than it adds value. Thus think twice about what and how to document your code. Good code doesn't require much documentation.
Example magnum
.gitattributes -> force LF line endings (document this) - some git distributions use 1310 when checking out files Vim has trouble with