spacemacs/doc/CONVENTIONS.org

Spacemacs Conventions

• Code guidelines
  • Spacemacs core and layer
  • All layers
  • Use-package
• Key bindings conventions
  • Reserved prefix
    • User prefix
    • Major mode prefix
    • Transient-state
  • Evilified buffers
  • Navigation
    • n and N
    • Code Navigation
    • insert state buffers
  • Confirm and Abort
  • Evaluation
  • REPLs
    • Send code
    • In terminal
  • Building and Compilation
  • Debugging
  • Errors
  • Plain Text Markup Languages
    • Headers
    • Insertion of common elements
    • Text manipulation
    • Movement in normal mode
    • Promotion, Demotion and element movement
    • Table editing
  • Tests
    • All languages
    • Language specific
  • Toggles
  • Refactoring
  • Imports
  • Code Formatting
  • Web frameworks
  • Help or Documentation
• Writing documentation
  • Spacing in documentation

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

Use-package

• Always use progn when a code block requires multiple lines for :init or :config keywords.
• If there is only one line of code then try to keep :init or :config keywords on the same line.
• Don't nest multiple use-package calls unless you have a very good reason to do it.

Key bindings conventions

Reserved prefix

User prefix

SPC o and SPC m o must not be used by any layer. They are reserved for the user.

Major mode prefix

SPC m is reserved for the current major mode. Three keys bindings are not an issue (ie. SPC m h d) since SPC m can be accessed via ​,​.

Transient-state

Transient states are generally put behin the dot key ., for instance the windows manipulation transient state in SPC w ..

When it is not possible to use the . (like in helm buffers) transient states should be enabled with M-SPC and s-M-SPC. We need the latter bindings on macOS since M-SPC is used by the OS for spotlight.

It is recommended to make sure that q allows to leave the transient-state.

Evilified buffers

Evilifying a buffer is to set the evilified state as the default state for the major mode of the buffer.

The evilified state is derived from the emacs state and modify the map to:

• add hjkl navigation
• add scrolling feature on C-f, C-b, C-d and C-u
• G and gg to go to the end and beginning of the buffer
• add incremental search with /, n and N
• enabling evil-ex on :
• add visual state and visual line state on v and V
• add yank on y in visual state only
• activate evil-leader key on SPC

Setting the evilified state to a mode is done by calling the macro evilified-state-evilify-map.

Evilification rebinds shadowed key bindings according to the following rules:

• alphabetic key bindings: x -> X -> C-x -> C-X
• SPC -> ​'​
• / -> \
• : -> |
• C-g cannot be shadowed

If a key binding cannot be remapped then it is ignored and a warning message is displayed in *Messages*.

Navigation

n and N

To be consistent with the Vim way, n and N are favored over Emacs n and p.

Ideally a transient-state should be provided to smooth the navigation experience. A transient-state allows to repeat key bindings without entering each time the prefix commands. More info on transient-states in the documentation.

Code Navigation

The prefix for going to something is SPC m g.

Key	Description
m g a	go to alternate file (i.e. .h <--> .cpp)
m g b	go back to previous location (before last jump)
m g g	go to things under point
m g G	go to things under point in other window
m g i	go to imports
m g t	go to corresponding test file if any
m g u	go/find usage of thing under point

insert state buffers

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

Key	Description
C-j	go down
C-k	go up

Confirm and Abort

Confirming and aborting actions which are bound to C-c C-c and C-c C-k in raw Emacs are mirrored in Spacemacs to:

Key	Description
SPC m ​,​ and SPC m c	Valid/Confirm the message
SPC m a and SPC m k	Abort/Discard the message

Some example of these modes are magit commit messages, message-mode for mails or org-mode notes.

Evaluation

Live evaluation of code is under the prefix SPC m e.

Key	Description
m e $	put point at the end of the line and evaluate
m e b	evaluate buffer
m e e	evaluate last expression
m e f	evaluate function
m e l	evaluate line
m e r	evaluate region

REPLs

Send code

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

• SPC m s is the prefix for sending code. This allows fast interaction with the REPL whenever it is possible
• lower case key bindings keep the focus on the current buffer
• upper case key bindings move the focus to the REPL buffer

Key	Description
m s b	send buffer
m s B	send buffer and switch to REPL
m s d	first key to send buffer and switch to REPL to debug (step)
m s D	second key to send buffer and switch to REPL to debug (step)
m s f	send function
m s F	send function and switch to REPL
m s i	start/switch to REPL inferior process
m s l	send line
m s L	send line and switch to REPL
m s r	send region
m s R	send region and switch to REPL

Note: we don't distinguish between the file and the buffer.

In terminal

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

Key	Description
C-j	next item in history
C-k	previous item in history
C-l	clear screen
C-r	search backward in history

Building and Compilation

The base prefix for major mode specific compilation is SPC m c.

Key binding	Description
m c b	compile buffer
m c c	compile
m c C	clean
m c r	clean and compile

Note: we don't distinguish between the file and the buffer. We can implement an auto-save of the buffer before compiling the buffer.

Debugging

The base prefix for debugging commands is SPC m d.

Key binding	Description
m d a	abandon current process
m d b	toggle a breakpoint
m d B	clear all breakpoints
m d c	continue
m d d	start debug session
m d i	step in
m d l	local variables
m d o	step out
m d r	run
m d s	next step
m d v	inspect value at point

Notes:

• Ideally a transient-state for breakpoint navigation should be provided.
• If there is no toggle breakpoint function, then it should be implemented at the spacemacs level and ideally the function should be proposed as a patch upstream (major mode repository).

Errors

Management of errors should be put under SPC m E.

Key binding	Description
m E e	fix error around point
m E l	show errors
m E L	show errors and jump to errors list

Plain Text Markup Languages

For layers supporting markup languages please follow the following keybindings whenever applicable.

Headers

All header functionality should be grouped under SPC m h

Key binding	Description
m h i	Insert a header
m h I	Insert a header alternative method (if existing)
m h 1..10	Insert a header of level 1..10 (if possible)

Insertion of common elements

Insertion of common elements like links or footnotes should be grouped under SPC m i

Key binding	Description
m i f	Insert footnote
m i i	Insert image
m i l	Insert link
m i u	Insert url
m i w	Insert wiki-link

Text manipulation

Manipulation of text regions should be grouped under SPC m x

Key binding	Description
m x b	Make region bold
m x c	Make region code
m x i	Make region italic
m x q	Quote a region
m x r	Remove formatting from region
m x s	Make region strike-through
m x u	Make region underlined
m x v	Make region verbatim

Movement in normal mode

In normal mode Vim style movement should be enabled with these key bindings:

Key binding	Description
g h	Move up one level in headings
g j	Move to next heading on same level
g k	Move to previous heading on same level
g l	Move down one level in headings

Promotion, Demotion and element movement

Promotion, demotion and movement of headings or list elements (whatever is possible) should be enabled with the following keys when in Vim style or Hybrid with hjkl movements enabled:

Key binding	Description
M-h	Promote heading by one level
M-j	Move element down
M-k	Move element up
M-l	Demote heading by one level

In all editing styles promotion and demotion can be done with the following keys:

Key binding	Description
M-down	Move element down
M-left	Promote heading by one level
M-right	Demote heading by one level
M-up	Move element up

Table editing

If table specific commands are available the they are grouped under the SPC m t group.

Tests

A lot of languages have their own test frameworks. These frameworks share common actions that we can unite under the same key bindings:

• SPC m t is the prefix for test execution.
• SPC m t g is the prefix for test generation.
• SPC m t X is used to execute SPC m t x but in debug mode (if supported).

All languages

Key	Description
m t a	execute all the tests of the current project
m t A	execute all the tests of the current project in debug
m t b	execute all the tests of the current buffer
m t B	execute all the tests of the current buffer in debug
m t l	execute the last executed test again
m t t	execute the current test (thing at point, function)
m t T	execute the current test in debug (thing at point, function)

Note: we don't distinguish between the file and the buffer. We can implement an auto-save of the buffer before executing the tests of buffer.

Language specific

Key	Description
m t m	execute the tests of the current module
m t M	execute the tests of the current module in debug
m t s	execute the tests of the current suite
m t S	execute the tests of the current suite in debug

Note that there are overlaps, depending on the language we will choose one or more bindings for the same thing

Toggles

• Global toggles are under SPC t, SPC T and SPC C-t
• Major mode toggles are only under SPC m T

Refactoring

Refactoring prefix is SPC m r.

Imports

When import management is supported the following key bindings should be used:

Key binding	Description
m i i	add import for symbol around point
m i f	fix/format imports
m g i	go to imports

Code Formatting

Major-mode code formatting is under prefix SPC m =.

Key binding	Description
m = =	format thing under point
m = b	format current buffer
m = f	format current function

Web frameworks

Web frameworks key bindings should go under SPC m f.

Help or Documentation

The base prefix for help commands is SPC m h. Documentation is considered as an help command.

Key	Description
m h h	documentation of thing under point
m h r	documentation of selected region

Writing documentation

Spacemacs provides an example layer README.org file in ~/.emacs.d/core/templates/README.org.template.

Spacing in documentation

• Spacemacs tries to keep the documentation consistent between all layers by providing some rules for spacing:

  • After each header, you should not add an empty line

    • Exception: If the first item under the header is a table, add an empty line after it
  • At the end of each header node, there should be an empty line
  • Note: Many layer READMEs do not follow this convention yet. Please fix them if you can.
• To keep things readable only mention the prefix SPC when documenting key bindings, you don't need to mention M-m.