From 90e80b9e8b6c8fedd2192c4d17a20cf13f5d8a37 Mon Sep 17 00:00:00 2001 From: DaanDeMeyer Date: Thu, 1 Jan 2026 21:09:26 +0100 Subject: [PATCH] docs: Document practice of using comments for argument names --- docs/CODING_STYLE.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/CODING_STYLE.md b/docs/CODING_STYLE.md index 02a776e544..a8c2ab0f8b 100644 --- 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