Document best practice on functions, naming and where (not) to use local

[matu3ba]

Nice idea to collect the stuff here @mfussenegger.

Copied from plans for an advanced nvim-lua-guide, since it fits better here:

1. Always use local on functions and variables except in yourpluginname.lua or if the plugin template/upstream project you depend on instructs you to make functions available to the user.
2. What should be used? local function a = bla() xor local a = function() xor function M.bla() ? Consistency please
3. Do not use underscope-prefix functions They are reserved by neovim for internal functionality.
4. If possible, provide initialisation functions inside your yourpluginname.lua to enable lazy-loading. This also prevents the lua-aware startup profiler to break: A Lua-aware startup time profiler wishlist#15 (comment)

[matu3ba]

kinda related are the code examples in #3, but I wanted to keep the reasoning separate.

[mfussenegger]

I think the "Things you should avoid" section may have been a mistake and bloated up the scope of this repository too much.

This isn't intended to become a "Lua plugin author guideline" or even authority in terms of what must be done and what not - but was merely intended as a starter template to make the setup a little easier and avoid having to deal with boilerplate.

I've pushed a change to the README to clarify that.

There's enough content already on how to write good Lua code. We don't need to replicate existing work, especially not in this repository.