docs: Document practice of using comments for argument names

(cherry picked from commit 90e80b9e8b)
This commit is contained in:
DaanDeMeyer
2026-01-01 21:09:26 +01:00
committed by Luca Boccassi
parent 758bba7844
commit 9af7887104

View File

@@ -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