18.5.4 Formatting Code

When writing Scheme code, we follow common wisdom among Scheme programmers. In general, we follow the Riastradh’s Lisp Style Rules. This document happens to describe the conventions mostly used in Guile’s code too. It is very thoughtful and well written, so please do read it.

Some special forms introduced in Guix, such as the substitute* macro, have special indentation rules. These are defined in the .dir-locals.el file, which Emacs automatically uses. Also note that Emacs-Guix provides guix-devel-mode mode that indents and highlights Guix code properly (see Development in The Emacs-Guix Reference Manual).

If you do not use Emacs, please make sure to let your editor knows these rules. To automatically indent a package definition, you can also run:

./pre-inst-env guix style package

See Invoking guix style, for more information.

If you are editing code with Vim, we recommend that you run :set autoindent so that your code is automatically indented as you type. Additionally, paredit.vim may help you deal with all these parentheses.

We require all top-level procedures to carry a docstring. This requirement can be relaxed for simple private procedures in the (guix build …) name space, though.

Procedures should not have more than four positional parameters. Use keyword parameters for procedures that take more than four parameters.