spacemacs/CONVENTIONS.md

Spacemacs conventions

Table of Contents

• Spacemacs conventions
  • Code guidelines
    • Spacemacs core and layer
    • All layers
  • Key bindings conventions
    • Prefix reserved to the user
    • Navigation in insert state buffers
    • Interactions with REPLs

Code guidelines

Spacemacs core and layer

Function names follow these conventions:

• spacemacs/xxx is an interactive function called xxx
• spacemacs//xxx is a private function called xxx (implementation details)
• spacemacs|xxx is a macro called xxx

Variables follow these conventions:

• spacemacs-xxx is a variable
• spacemacs--xxx is a private variable (implementation details)

All layers

A package is initialized in a function with name <layer>/init-xxx where:

• <layer> is the layer name
• xxx is the package name

Key bindings conventions

Prefix reserved to the user

<SPC> o must not be used by any layer. It is reserved for the user.

Evilify buffers

Spacemacs offers convenient functions to evilify a buffer. Evilifying a buffer is to:

• add hjkl navigation
• add incremental search with /, n and N
• add visual state and visual line state
• activate evil-leader key
• fix all bindings shadows by the above additions

To fix the shadowed bindings we capitalize them, for instance: shadowed h is transposed to H, if H is taken then it is transposed to C-h and so on...

Example of evilified buffers are magit status, paradox buffer.

The related functions are:

• spacemacs/activate-evil-leader-for-maps and spacemacs/activate-evil-leader-for-map
• spacemacs/evilify

Navigation in insert state buffers

Navigation in buffers like Helm and ido which are in insert state should be performed with C-j and C-k for vertical movements.

History navigation in shells or REPLs buffers should be bound as well to C-j and C-k.

Interactions with REPLs

A lot of languages can interact with a REPL. To help keeping a consistent behavior between those languages the following conventions should be followed:

• lower case key bindings keep the focus on the current buffer
• upper case key bindings move the focus to the REPL buffer

  Key	Description
  b	evaluate buffer
  B	evaluate buffer and switch to REPL
  f	evaluate function
  F	evaluate function and switch to REPL
  l	evaluate line
  L	evaluate line and switch to REPL
  r	evaluate region
  R	evaluate region and switch to REPL