blob: fd2456ea4509c6283ce7e0e25b5f519e0b6918ed [file] [view] [edit]
---
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:
```cpp
// 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:
```cpp
// 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
```