blob: 882a206724f97748513213fdabbc6f0023c82451 [file] [view] [edit]
---
name: libaom/use-bool-for-boolean-flags-and-arrays
description: When declaring, assigning, or evaluating boolean flags, struct members, arrays, pointers, or predicates, use bool with <stdbool.h>, true/false, direct checks, and inline call-site comments
rubric: readability
severity: blocking
---
**Rule.** In C and dual C/C++ code, use `bool` (explicitly including
`<stdbool.h>` in `.c` and `.h` files rather than relying on transitive includes)
instead of integer types (`int`, `unsigned int`, `uint32_t`, `uint8_t`) for
predicate functions, local variables, flags, struct members, status arrays,
binary status return types, and out-parameters (`bool *` instead of `int *`). Do
not split boolean field types across `#ifdef __cplusplus` guards.
Follow these conventions for boolean usage:
1. **Literals & Conditions**: In assignments, initializations, and returns, use boolean literals `true` and `false` rather than `1` and `0`. Evaluate boolean expressions directly (`if (flag)`, `if (!flag)`) rather than comparing against literals or zero (`== true`, `== false`, `== 1`, `== 0`, `!= 0`).
2. **Explicit Conversions**: Explicitly compare against zero (`!= 0` or `> 0`) when converting bitwise mask checks (e.g., `(flags & MASK) != 0`), comparison function results (e.g., `strcmp(...) != 0`), or multi-valued integer settings/enums to boolean values or function arguments.
3. **Call-Site Annotations & Comments**: Annotate non-obvious boolean literal arguments at call sites with inline parameter-name comments (e.g., `/*param=*/false`). Document ambiguous boolean return value semantics (e.g., `// Returns true on success, false on failure.`) above function declarations in headers, and use `true`/`false` rather than `1`/`0` in code comments.
**Why.** Explicitly including `<stdbool.h>` avoids brittle transitive header
dependencies that break during refactoring. Using standard `bool` with
`true`/`false` enforces strong type safety, clarifies binary intent, avoids
`#ifdef __cplusplus` preprocessor branching, reduces struct memory footprints (1
byte vs. 4 bytes), and prevents pointer type mismatches on output parameters.
Direct conditional checks eliminate redundant comparisons. Explicit conversions
(`!= 0`) clarify intentional truth-value conversions from bitmasks or
multi-level features without implicit truncation. Inline parameter comments
(`/*param=*/false`) make call sites self-documenting without requiring function
signature lookups.
## Examples
Bad:
```cpp
// Bad: missing <stdbool.h>, using int / #ifdef for flags, out-params, comparisons
struct SvcRtcRef {
#if defined(__cplusplus)
bool is_key_frame;
#else
int is_key_frame;
#endif
unsigned int enable_cdef;
int is_frame_dropped[MAX_STATIC_GF_GROUP_LENGTH];
};
int check_neighbor_blk(const MACROBLOCKD *xd, int *use_scaled_ref) {
int using_file = strcmp(fn, "-");
bool is_layer_obu = metadata->flags & AOM_MIF_LAYER_SPECIFIC;
if (is_layer_obu == 1 || is_screen == false) return 1;
return 0;
}
diffwtd_mask_neon(mask, 0, src0, src0_stride, src1, src1_stride, h, w);
av1_pick_cdef_from_qp(cm, cpi->sf.rt_sf.skip_cdef_sb, is_screen, avoid_uv);
```
Good:
```cpp
// Good: explicit <stdbool.h>, bool everywhere, true/false, inline comments, != 0
#include <stdbool.h>
struct SvcRtcRef {
bool is_key_frame;
bool enable_cdef;
bool is_frame_dropped[MAX_STATIC_GF_GROUP_LENGTH];
};
// Returns true if neighbor block is valid, false otherwise.
bool check_neighbor_blk(const MACROBLOCKD *xd, bool *use_scaled_ref) {
const bool using_file = strcmp(fn, "-") != 0;
const bool is_layer_obu = (metadata->flags & AOM_MIF_LAYER_SPECIFIC) != 0;
if (is_layer_obu || !is_screen) return true;
return false;
}
diffwtd_mask_neon(mask, /*inverse=*/false, src0, src0_stride, src1, src1_stride, h, w);
av1_pick_cdef_from_qp(cm, cpi->sf.rt_sf.skip_cdef_sb != 0, is_screen, avoid_uv);
```