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.
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