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:

// 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:

// 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);