summary refs log tree commit diff
path: root/HACKING
diff options
context:
space:
mode:
authorLudovic Courtès <ludo@gnu.org>2013-08-30 23:46:58 +0200
committerLudovic Courtès <ludo@gnu.org>2013-08-30 23:47:23 +0200
commite1c5a8357ad1d473ecf6d12b7b4a327705c10605 (patch)
tree356fa1bfee3e5b9695bdd59a3c750275ee58df22 /HACKING
parent67b1dd8dea0e291a55717c844a28113d83647eb6 (diff)
downloadguix-e1c5a8357ad1d473ecf6d12b7b4a327705c10605.tar.gz
doc: Add a "Coding Style" section in 'HACKING'.
* HACKING (Coding Style): New section.
Diffstat (limited to 'HACKING')
-rw-r--r--HACKING34
1 files changed, 34 insertions, 0 deletions
diff --git a/HACKING b/HACKING
index caa3e95b3a..514179227e 100644
--- a/HACKING
+++ b/HACKING
@@ -88,6 +88,40 @@ guix-devel@gnu.org.  Please write commit logs in the [[http://www.gnu.org/prep/s
 As you become a regular contributor, you may find it convenient to have write
 access to the repository (see below.)
 
+* Coding Style
+
+In general our code follows the [[info:standards][GNU Coding Standards]] (GCS).  However, the GCS
+do not say much about Scheme, so here are some additional rules.
+
+** Programming Paradigm
+
+Scheme code in Guix is written in a purely functional style.  One exception is
+code that involves input/output, and procedures that implement low-level
+concepts, such as the ‘memoize’ procedure.
+
+** Modules
+
+Guile modules that are meant to be used on the builder side must live in the
+(guix build …) name space.  They must not refer to other Guix or GNU modules.
+However, it is OK for a “host-side” module to use a build-side module.
+
+Modules that deal with the broader GNU system should be in the (gnu …) name
+space rather than (guix …).
+
+** Formatting Code
+
+When writing Scheme code, we follow common wisdom among Scheme programmers.
+In general, we follow the [[http://mumble.net/~campbell/scheme/style.txt][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.
+
+In addition, 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.
+
 * Commit Access
 
 For frequent contributors, having write access to the repository is