17.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:

./etc/indent-code.el gnu/packages/file.scm package

This automatically indents the definition of package in gnu/packages/file.scm by running Emacs in batch mode. To indent a whole file, omit the second argument:

./etc/indent-code.el gnu/services/file.scm

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.