* Description of the current coding conventions in Nixpkgs / NixOS.

  Comments welcome.

svn path=/nixpkgs/trunk/; revision=10392

1 files changed, 97 insertions, 0 deletions

diff --git a/maintainers/docs/coding-conventions.txt b/maintainers/docs/coding-conventions.txt
new file mode 100644
index 0000000000000..c95dc3c36009f
--- /dev/null
+++ b/maintainers/docs/coding-conventions.txt
@@ -0,0 +1,97 @@
+Some conventions:
+
+* Don't use TABs.  Everybody has different TAB settings so it's asking
+  for trouble.
+
+* Use 2 spaces of indentation per indentation level in Nix
+  expressions, 4 spaces in shell scripts.  (Maybe 2 is too low, but
+  for consistency's sake it should be the same.  Certainly indentation
+  should be consistent within a single file.)
+
+* Use lowerCamelCase for variable names, not UpperCamelCase.
+
+* Function calls with attribute set arguments are written as
+
+    foo {
+      arg = ...;
+    }
+
+  not
+
+    foo
+    {
+      arg = ...;
+    }
+
+  Also fine is
+
+    foo { arg = ...; }
+
+  if it's a short call.
+
+* In attribute sets or lists that span multiple lines, the attribute
+  names or list elements should be aligned:
+
+    # A long list.
+    list = [
+      elem1
+      elem2
+      elem3
+    ];
+
+    # A long attribute set.
+    attrs = {
+      attr1 = short_expr;
+      attr2 =
+        if true then big_expr else big_expr;
+    };
+    
+* Short lists or attribute sets can be written on one line:
+    
+    # A short list.
+    list = [ elem1 elem2 elem3 ];
+
+    # A short set.
+    attrs = { x = 1280; y = 1024; };
+
+* Breaking in the middle of a function argument can give hard-to-read
+  code, like
+
+    someFunction { x = 1280;
+      y = 1024; } otherArg
+      yetAnotherArg
+
+  (especially if the argument is very large, spanning multiple lines).
+
+  Better:
+
+    someFunction
+      { x = 1280; y = 1024; }
+      otherArg
+      yetAnotherArg
+
+  or
+    
+    let res = { x = 1280; y = 1024; };
+    in someFunction res otherArg yetAnotherArg
+
+* The bodies of functions, asserts, and withs are not indented, so
+
+    assert system == "i686-linux";
+    stdenv.mkDerivation { ...
+
+  not
+
+    assert system == "i686-linux";
+      stdenv.mkDerivation { ...
+
+* Function formal arguments are written as:
+
+    {arg1, arg2, arg3}:
+
+  but if they don't fit on one line they're written as:
+
+    { arg1, arg2, arg3
+    , arg4, ...
+    , argN
+    }: