*dev_style.txt*          Nvim


                            NVIM REFERENCE MANUAL


Nvim style guide                                        *dev-style*

Style guidelines for developers working Nvim's source code.

License: CC-By 3.0 https://creativecommons.org/licenses/by/3.0/

                                      Type |gO| to see the table of contents.

==============================================================================
Background

One way in which we keep the code base manageable is by enforcing consistency.
It is very important that any programmer be able to look at another's code and
quickly understand it.

Maintaining a uniform style and following conventions means that we can more
easily use "pattern-matching" to infer what various symbols are and what
invariants are true about them. Creating common, required idioms and patterns
makes code much easier to understand.

In some cases there might be good arguments for changing certain style rules,
but we nonetheless keep things as they are in order to preserve consistency.


==============================================================================
Header Files                                            *dev-style-header*


Header guard ~

All header files should start with `#pragma once` to prevent multiple inclusion.

    In foo/bar.h:
>c
        #pragma once
<

Headers system ~

Nvim uses two types of headers. There are "normal" headers and "defs" headers.
Typically, each normal header will have a corresponding defs header, e.g.
`fileio.h` and `fileio_defs.h`. This distinction is done to minimize
recompilation on change. The reason for this is because adding a function or
modifying a function's signature happens more frequently than changing a type
The goal is to achieve the following:

- All headers (defs and normal) must include only defs headers, system
  headers, and generated declarations. In other words, headers must not
  include normal headers.

- Source (.c) files may include all headers, but should only include normal
  headers if they need symbols and not types.

Use the following guideline to determine what to put where:

Symbols:
  - regular function declarations
  - `extern` variables (including the `EXTERN` macro)

Non-symbols:
  - macros, i.e. `#define`
  - static inline functions with the `FUNC_ATTR_ALWAYS_INLINE` attribute
  - typedefs
  - structs
  - enums

- All symbols must be moved to normal headers.

- Non-symbols used by multiple headers should be moved to defs headers. This
  is to ensure headers only include defs headers. Conversely, non-symbols used
  by only a single header should be moved to that header.

- EXCEPTION: if the macro calls a function, then it must be moved to a normal
  header.

==============================================================================
Scoping                                                 *dev-style-scope*

Local Variables ~

Place a function's variables in the narrowest scope possible, and initialize
variables in the declaration.

C99 allows you to declare variables anywhere in a function. Declare them in as
local a scope as possible, and as close to the first use as possible. This
makes it easier for the reader to find the declaration and see what type the
variable is and what it was initialized to. In particular, initialization
should be used instead of declaration and assignment, e.g. >c

    int i;
    i = f();      // ❌: initialization separate from declaration.

    int j = g();  // ✅: declaration has initialization.


Initialization ~

Multiple declarations can be defined in one line if they aren't initialized,
but each initialization should be done on a separate line.

>c
    int i;
    int j;              // ✅
    int i, j;           // ✅: multiple declarations, no initialization.
    int i = 0;
    int j = 0;          // ✅: one initialization per line.

    int i = 0, j;       // ❌: multiple declarations with initialization.
    int i = 0, j = 0;   // ❌: multiple declarations with