426 lines
17 KiB
Org Mode
426 lines
17 KiB
Org Mode
#+TITLE: Spacemacs Conventions
|
||
|
||
* Table of Contents :TOC_5_gh:noexport:
|
||
- [[#code-guidelines][Code guidelines]]
|
||
- [[#spacemacs-core-and-layer][Spacemacs core and layer]]
|
||
- [[#all-layers][All layers]]
|
||
- [[#use-package][Use-package]]
|
||
- [[#key-bindings-conventions][Key bindings conventions]]
|
||
- [[#reserved-prefix][Reserved prefix]]
|
||
- [[#user-prefix][User prefix]]
|
||
- [[#major-mode-prefix][Major mode prefix]]
|
||
- [[#transient-state][Transient-state]]
|
||
- [[#special-mode-buffers][Special-mode buffers]]
|
||
- [[#evilified-buffers][Evilified buffers]]
|
||
- [[#navigation][Navigation]]
|
||
- [[#n-and-n][n and N]]
|
||
- [[#code-navigation][Code Navigation]]
|
||
- [[#insert-state-buffers][=insert state= buffers]]
|
||
- [[#confirm-and-abort][Confirm and Abort]]
|
||
- [[#evaluation][Evaluation]]
|
||
- [[#repls][REPLs]]
|
||
- [[#send-code][Send code]]
|
||
- [[#in-terminal][In terminal]]
|
||
- [[#building-and-compilation][Building and Compilation]]
|
||
- [[#debugging][Debugging]]
|
||
- [[#errors][Errors]]
|
||
- [[#plain-text-markup-languages][Plain Text Markup Languages]]
|
||
- [[#headers][Headers]]
|
||
- [[#insertion-of-common-elements][Insertion of common elements]]
|
||
- [[#text-manipulation][Text manipulation]]
|
||
- [[#movement-in-normal-mode][Movement in normal mode]]
|
||
- [[#promotion-demotion-and-element-movement][Promotion, Demotion and element movement]]
|
||
- [[#table-editing][Table editing]]
|
||
- [[#tests][Tests]]
|
||
- [[#all-languages][All languages]]
|
||
- [[#language-specific][Language specific]]
|
||
- [[#toggles][Toggles]]
|
||
- [[#refactoring][Refactoring]]
|
||
- [[#imports][Imports]]
|
||
- [[#code-formatting][Code Formatting]]
|
||
- [[#web-frameworks][Web frameworks]]
|
||
- [[#help-or-documentation][Help or Documentation]]
|
||
- [[#writing-documentation][Writing documentation]]
|
||
- [[#spacing-in-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 behind 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.
|
||
|
||
** Special-mode buffers
|
||
Except for =eww-mode= and evilified buffers (see next section), all buffers with
|
||
major-modes derived from =special-mode= open in motion-state by default. To
|
||
exclude buffers of such major-modes from getting evilified, add a regexp to
|
||
=evil-buffer-regexps=.
|
||
|
||
** 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 jump back-forward in history on ~C-o~ and ~C-i~ respectively
|
||
- 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
|
||
[[https://github.com/syl20bnr/spacemacs/blob/develop/doc/DOCUMENTATION.org#transient-states][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~.
|