doc: add function argument order convention (#110060)

* doc: add function argument order convention

Ordering by usage is the de facto ordering given to arguments. It's
logical, and makes finding argument usage easier. Putting lib first is
common in NixOS modules, so it's reasonable to mirror this in nixpkgs
proper. Additionally, it's not a package as such, has zero dependencies,
and can be found used anywhere in a derivation.

* doc: clean up usage of lib

1 files changed, 6 insertions, 0 deletions

diff --git a/doc/contributing/coding-conventions.xml b/doc/contributing/coding-conventions.xml
index cb6d60c2c13..9005a9ebafd 100644
--- a/doc/contributing/coding-conventions.xml
+++ b/doc/contributing/coding-conventions.xml
@@ -180,6 +180,12 @@ args.stdenv.mkDerivation (args // {
    </listitem>
    <listitem>
     <para>
+     Arguments should be listed in the order they are used, with the
+     exception of <varname>lib</varname>, which always goes first.
+    </para>
+   </listitem>
+   <listitem>
+    <para>
      Prefer using the top-level <varname>lib</varname> over its alias
      <literal>stdenv.lib</literal>.  <varname>lib</varname> is unrelated to
      <varname>stdenv</varname>, and so <literal>stdenv.lib</literal> should only