From e4d5933e0a81373b7870cf6a9b5b4c28ab9a57df Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <eelco.dolstra@logicblox.com>
Date: Wed, 18 Nov 2009 10:52:37 +0000
Subject: * "with args" considered harmful.

svn path=/nixpkgs/trunk/; revision=18404
---
 doc/coding-conventions.xml | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

(limited to 'doc')

diff --git a/doc/coding-conventions.xml b/doc/coding-conventions.xml
index 3e4afdc1d4f5f..586fcd98f23d8 100644
--- a/doc/coding-conventions.xml
+++ b/doc/coding-conventions.xml
@@ -152,6 +152,52 @@ stdenv.mkDerivation { ...
 , # Some comment...
   argN
 }:
+</programlisting>
+
+  </para></listitem>
+
+  <listitem><para>Functions should list their expected arguments as
+  precisely as possible.  That is, write
+
+<programlisting>
+{ stdenv, fetchurl, perl }: <replaceable>...</replaceable>
+</programlisting>
+
+  instead of
+
+<programlisting>
+args: with args; <replaceable>...</replaceable>
+</programlisting>
+
+  or 
+  
+<programlisting>
+{ stdenv, fetchurl, perl, ... }: <replaceable>...</replaceable>
+</programlisting>
+
+  </para>
+
+  <para>For functions that are truly generic in the number of
+  arguments (such as wrappers around <varname>mkDerivation</varname>)
+  that have some required arguments, you should write them using an
+  <literal>@</literal>-pattern:
+
+<programlisting>
+{ stdenv, doCoverageAnalysis ? false, ... } @ args:
+
+stdenv.mkDerivation (args // {
+  <replaceable>...</replaceable> if doCoverageAnalysis then "bla" else "" <replaceable>...</replaceable>
+})
+</programlisting>
+
+  instead of
+
+<programlisting>
+args:
+
+args.stdenv.mkDerivation (args // {
+  <replaceable>...</replaceable> if args ? doCoverageAnalysis &amp;&amp; args.doCoverageAnalysis then "bla" else "" <replaceable>...</replaceable>
+})
 </programlisting>
 
   </para></listitem>
-- 
cgit 1.4.1