CodingGuidelines: also mention MAYBE_UNUSED
A function that uses a parameter in one build may lose all uses of the parameter in another build, depending on the configuration. A workaround for such a case, MAYBE_UNUSED, should also be mentioned when we recommend the use of UNUSED to our developers. Keep the addition to the guideline short and document the criteria to choose between UNUSED and MAYBE_UNUSED near their definition. Signed-off-by: Junio C Hamano <gitster@pobox.com>
Junio C Hamano committed
Aug 29, 2024 at 11:18 UTC
a051ca5e650138230f3dd61bda911f0f409ebf23
2 files changed
+27
-2
Documentation/CodingGuidelines
+3
-2
@@ -262,8 +262,9 @@ For C programs:
262
like "error: unused parameter 'foo' [-Werror=unused-parameter]",
263
which indicates that a function ignores its argument. If the unused
264
parameter can't be removed (e.g., because the function is used as a
265
- callback and has to match a certain interface), you can annotate the
266
- individual parameters with the UNUSED keyword, like "int foo UNUSED".
265
+ callback and has to match a certain interface), you can annotate
266
+ the individual parameters with the UNUSED (or MAYBE_UNUSED)
267
+ keyword, like "int foo UNUSED".
268
269
- We try to support a wide range of C compilers to compile Git with,
270
including old ones. As of Git v2.35.0 Git requires C99 (we check
git-compat-util.h
+24
@@ -195,6 +195,19 @@ struct strbuf;
195
#define _NETBSD_SOURCE 1
196
#define _SGI_SOURCE 1
197
198
+/*
199
+ * UNUSED marks a function parameter that is always unused. It also
200
+ * can be used to annotate a function, a variable, or a type that is
201
+ * always unused.
202
+ *
203
+ * A callback interface may dictate that a function accepts a
204
+ * parameter at that position, but the implementation of the function
205
+ * may not need to use the parameter. In such a case, mark the parameter
206
+ * with UNUSED.
207
+ *
208
+ * When a parameter may be used or unused, depending on conditional
209
+ * compilation, consider using MAYBE_UNUSED instead.
210
+ */
211
#if GIT_GNUC_PREREQ(4, 5)
212
#define UNUSED __attribute__((unused)) \
213
__attribute__((deprecated ("parameter declared as UNUSED")))
@@ -649,6 +662,17 @@ static inline int git_has_dir_sep(const char *path)
662
#define RESULT_MUST_BE_USED
663
#endif
664
665
+/*
666
+ * MAYBE_UNUSED marks a function parameter that may be unused, but
667
+ * whose use is not an error. It also can be used to annotate a
668
+ * function, a variable, or a type that may be unused.
669
+ *
670
+ * Depending on a configuration, all uses of such a thing may become
671
+ * #ifdef'ed away. Marking it with UNUSED would give a warning in a
672
+ * compilation where it is indeed used, and not marking it at all
673
+ * would give a warning in a compilation where it is unused. In such
674
+ * a case, MAYBE_UNUSED is the appropriate annotation to use.
675
+ */
676
#define MAYBE_UNUSED __attribute__((__unused__))
677
678
#include "compat/bswap.h"