docs: Document practice of using comments for argument names

diff --git a/docs/CODING_STYLE.md b/docs/CODING_STYLE.md
index 02a776e54462f707cee84a02dd462345f749f6c4..a8c2ab0f8bf8c5b1f0a1b6d47ac34341b5fa2d43 100644 (file)
--- a/docs/CODING_STYLE.md
+++ b/docs/CODING_STYLE.md
@@ -247,6 +247,24 @@ SPDX-License-Identifier: LGPL-2.1-or-later
                   const char *input);
   ```
 
+- When passing `NULL` or another value meaning "unset" to a function, use a comment
+  to indicate the argument name to make it more clear where we're passing an "unset"
+  value.
+
+  Bad:
+
+  ```c
+  myfunction(NULL, NULL, NULL);
+  ```
+
+  Good:
+
+  ```c
+  myfunction(/* a= */ NULL, /* b= */ NULL, /* c= */ NULL);
+  ```
+
+  This guidance should be applied tree-wide, including in test files.
+
 - Please do not introduce new circular dependencies between header files.
   Effectively this means that if a.h includes b.h, then b.h cannot include a.h,
   directly or transitively via another header. Circular header dependencies can