name: libaom/trailing-comment-on-endif-directives description: ‘Annotate #endif and #else on long preprocessor blocks and header guards with matching condition comments formatted without directive keywords, omitting on short blocks’ rubric: readability severity: blocking

Rule. Annotate #endif and #else directives on long or multi-function preprocessor blocks and header guards with trailing comments accurately matching the opening condition, macro name, or guard token (e.g., #endif // CONFIG_AV1_HIGHBITDEPTH, #else // !CONFIG_CTX_ADAPT_LOG_WEIGHT, #endif // AOM_AV1_COMMON_CCSO_H_). Format closing comments cleanly as #endif // <CONDITION> or #endif // <MACRO> without repeating preprocessor directive keywords like #if (e.g., avoid #endif // #if defined(...)). When modifying multi-branch blocks (#if/#elif/#endif), ensure #endif comments remain synchronized with the opening #if condition rather than referencing an inner #elif, and ensure #else comments accurately reflect the inverted condition. Maintain consistent directive styles within each file (prefer #ifdef MACRO or #ifndef MACRO for standalone identifiers over #if defined(...)). Conversely, omit trailing comments on short, locally visible #if blocks or when expressions would wrap across multiple comment lines.

Why. In preprocessor blocks spanning many lines, multiple functions, or header guards, trailing comments on #else and #endif clarify directive boundaries and compilation scopes without requiring readers to scroll back. Accurately formatted comments without repeated #if tokens comply with project conventions and cpplint rules. Comments referencing inner #elif branches or copy-pasted guard names mislead maintainers about active build configurations, while commenting short, locally visible blocks adds unnecessary visual clutter.

Examples

Bad:

// Variant 1: Bare #else / #endif on multi-line functions or mismatched header guard
#ifndef AOM_AV1_COMMON_CCSO_H_
#define AOM_AV1_COMMON_CCSO_H_
#if CONFIG_AV1_HIGHBITDEPTH
static void highbd_pred(...) { /* multi-line implementation */ }
#endif
#endif  // AOM_AV1_COMMON_CDEF_H_

// Variant 2: Repeating directive token #if or referencing #elif instead of opening #if
#if defined(CONFIG_AV1_ENCODER)
void encode_frame(void);
#endif  // #if defined(CONFIG_AV1_ENCODER)

#if defined(__aarch64__) && defined(__ARM_FEATURE_MATMUL_INT8)
void process_neon(...);
#elif defined(__aarch64__) && defined(__ARM_FEATURE_DOTPROD)
void process_neon(...);
#endif  // defined(__aarch64__) && defined(__ARM_FEATURE_DOTPROD)

// Variant 3: Unnecessary multi-line comment on short, locally visible block
#if defined(AOM_ADDRESS_SANITIZER) && !defined(NDEBUG)
const size_t kMinStackSize = 1024 * 1024;
#else
const size_t kMinStackSize = 256 * 1024;
#endif  // defined(AOM_ADDRESS_SANITIZER) && !defined(NDEBUG)

Good:

// Variant 1: Annotated #else / #endif matching opening condition and header guard
#ifndef AOM_AV1_COMMON_CCSO_H_
#define AOM_AV1_COMMON_CCSO_H_
#if CONFIG_AV1_HIGHBITDEPTH
static void highbd_pred(...) { /* multi-line implementation */ }
#endif  // CONFIG_AV1_HIGHBITDEPTH
#endif  // AOM_AV1_COMMON_CCSO_H_

// Variant 2: Clean comment without directive token, synchronized with opening #if
#ifdef CONFIG_AV1_ENCODER
void encode_frame(void);
#endif  // CONFIG_AV1_ENCODER

#if defined(__aarch64__) && defined(__ARM_FEATURE_MATMUL_INT8)
void process_neon(...);
#elif defined(__aarch64__) && defined(__ARM_FEATURE_DOTPROD)
void process_neon(...);
#endif  // defined(__aarch64__) && defined(__ARM_FEATURE_MATMUL_INT8)

// Variant 3: Omit trailing comment on short, locally visible block
#if defined(AOM_ADDRESS_SANITIZER) && !defined(NDEBUG)
const size_t kMinStackSize = 1024 * 1024;
#else
const size_t kMinStackSize = 256 * 1024;
#endif