Minimize the
  knowledge spread to other parts of the code.


NVIM IS... NOT                                          *design-not*

Nvim is not an operating system; instead it should be composed with other
tools or hosted as a component. Marvim once said: "Unlike Emacs, Nvim does not
include the kitchen sink... but it's good for plumbing."


==============================================================================
Developer guidelines                                    *dev-guidelines*


PROVIDERS                                               *dev-provider*

A primary goal of Nvim is to allow extension of the editor without special
knowledge in the core.  Some core functions are delegated to "providers"
implemented as external scripts.

Examples:

1. In the Vim source code, clipboard logic accounts for more than 1k lines of
   C source code (ui.c), to perform two tasks that are now accomplished with
   shell commands such as xclip or pbcopy/pbpaste.

2. Python scripting support: Vim has three files dedicated to embedding the
   Python interpreter: if_python.c, if_python3.c and if_py_both.h. Together
   these files sum about 9.5k lines of C source code. In contrast, Nvim Python
   scripting is performed by an external host process implemented in ~2k lines
   of Python.

The provider framework invokes Vimscript from C.  It is composed of two
functions in eval.c:

- eval_call_provider({name}, {method}, {arguments}, {discard}): Calls
  `provider#{name}#Call` with {method} and {arguments}. If {discard} is true, any
  value returned by the provider will be discarded and empty value will be
  returned.
- eval_has_provider({name}): Checks the `g:loaded_{name}_provider` variable
  which must be set to 2 by the provider script to indicate that it is
  "enabled and working". Called by |has()| to check if features are available.

For example, the Python provider is implemented by the
"autoload/provider/python.vim" script, which sets `g:loaded_python_provider`
to 2 only if a valid external Python host is found.  Then `has("python")`
reflects whether Python support is working.

                                                        *provider-reload*
Sometimes a GUI or other application may want to force a provider to
"reload".  To reload a provider, undefine its "loaded" flag, then use
|:runtime| to reload it: >vim

    :unlet g:loaded_clipboard_provider
    :runtime autoload/provider/clipboard.vim


DOCUMENTATION                                           *dev-doc*

- "Just say it". Avoid mushy, colloquial phrasing in all documentation
  (docstrings, user manual, website materials, newsletters, …). Don't mince
  words. Personality and flavor, used sparingly, are welcome--but in general,
  optimize for the reader's time and energy: be "precise yet concise".
    - Prefer the active voice: "Foo does X", not "X is done by Foo".
    - "The words you choose are an essential part of the user experience."
      https://developer.apple.com/design/human-interface-guidelines/writing
    - "...without being overly colloquial or frivolous."
      https://developers.google.com/style/tone
- Write docstrings (as opposed to inline comments) with present tense ("Gets"),
  not imperative ("Get"). This tends to reduce ambiguity and improve clarity
  by describing "What" instead of "How". >
    ✅ OK:
    /// Gets a highlight definition.
    ❌ NO:
    /// Get a highlight definition.
- Avoid starting docstrings with "The" or "A" unless needed to avoid
  ambiguity. This is a visual aid and reduces noise. >
    ✅ OK:
    /// @param dirname Path fragment before `pend`
    ❌ NO:
    /// @param dirname The path fragment before `pend`
- Vim differences:
    - Do not prefix help tags with "nvim-". Use |vim_diff.txt| to catalog
      differences from Vim; no other distinction is necessary.
    - If a Vim feature is removed, delete its help section and move its tag to
      |vim_diff.txt|.
- Mention deprecated features in |deprecated.txt| and delete their old doc.