Skip to content

Latest commit

 

History

History
378 lines (313 loc) · 14.9 KB

CONVENTIONS.org

File metadata and controls

378 lines (313 loc) · 14.9 KB

Spacemacs Conventions

Spacemacs conventions

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

Whenever possible a transient-state should be enabled with M-SPC and s-M-SPC. We need the latter bindings on OS X since M-SPC is used by the OS for spotlight.

For instance transient-states dedicated to special buffers like helm or ido buffers are good candidates to be put on M-SPC and s-M-SPC.

It is recommended to add q 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 spacemacs|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.

KeyDescription
m g ago to alternate file (i.e. .h <--> .cpp)
m g bgo back to previous location (before last jump)
m g ggo to things under point
m g Ggo to things under point in other window
m g tgo to corresponding test file if any

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.

KeyDescription
C-jgo down
C-kgo 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:

KeyDescription
SPC m ​,​ and SPC m cValid/Confirm the message
SPC m a and SPC m kAbort/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.

KeyDescription
m e $put point at the end of the line and evaluate
m e bevaluate buffer
m e eevaluate last expression
m e fevaluate function
m e levaluate line
m e revaluate 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
KeyDescription
m s bsend buffer
m s Bsend buffer and switch to REPL
m s dfirst key to send buffer and switch to REPL to debug (step)
m s Dsecond key to send buffer and switch to REPL to debug (step)
m s fsend function
m s Fsend function and switch to REPL
m s istart/switch to REPL inferior process
m s lsend line
m s Lsend line and switch to REPL
m s rsend region
m s Rsend 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.

KeyDescription
C-jnext item in history
C-kprevious item in history
C-lclear screen
C-rsearch backward in history

Building and Compilation

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

Key BindingDescription
m c bcompile buffer
m c ccompile
m c Cclean
m c rclean 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 d.

Key BindingDescription
m d aabandon current process
m d btoggle a breakpoint
m d Bclear all breakpoints
m d ccontinue
m d dstart debug session
m d istep in
m d llocal variables
m d ostep out
m d rrun
m d snext step
m d vinspect 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).

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 BindingDescription
m h iInsert a header
m h IInsert a header alternative method (if existing)
m h 1..10Insert 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 BindingDescription
m i fInsert footnote
m i iInsert image
m i lInsert link
m i uInsert url
m i wInsert wiki-link

Text manipulation

Manipulation of text regions should be grouped under SPC m x

Key BindingDescription
m x bMake region bold
m x cMake region code
m x iMake region italic
m x qQuote a region
m x rRemove formatting from region
m x sMake region strike-through
m x uMake region underlined
m x vMake region verbose

Movement in normal mode

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

Key BindingDescription
g hMove up one level in headings
g jMove to next heading on same level
g kMove to previous heading on same level
g lMove 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 in any mode

Key BindingDescription
M-hPromote heading by one level
M-jMove element down
M-kMove element up
M-lDemote heading by one level

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 X is used to execute SPC m t x but in debug mode (if supported).

All languages

KeyDescription
m t aexecute all the tests of the current project
m t Aexecute all the tests of the current project in debug
m t bexecute all the tests of the current buffer
m t Bexecute all the tests of the current buffer in debug
m t texecute the current test (thing at point, function)
m t Texecute 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

KeyDescription
m t mexecute the tests of the current module
m t Mexecute the tests of the current module in debug
m t sexecute the tests of the current suite
m t Sexecute 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.

Code Formatting

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

Key BindingDescription
m = =format thing under point
m = bformat current buffer
m = fformat current function

Help or Documentation

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

KeyDescription
m h hdocumentation of thing under point
m h rdocumentation 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.