name: libaom/av1/document-speed-feature-levels-and-validation-checks description: When defining or modifying encoder speed features, heuristic flags, or search enums, document affected parameters, mode restrictions, pipeline stages, metric sources, and per-level fallback conditions rubric: readability severity: should_fix

Rule. When defining or modifying encoder speed features, heuristic flags, thresholds, or search enums in SPEED_FEATURES structs and speed_features.h, document their exact behavior in comments. Specify the concrete encoder state or parameter being modified (e.g., rc_bits_per_mb) and the intended objective (e.g., reducing overshoot) rather than vague summaries. Explicitly document applicable pipeline stages (e.g., MODE_EVAL vs. WINNER_MODE_EVAL), operating mode restrictions (such as all-intra mode or keyframes only), interactions with base speed features, metric sources (e.g., estimated vs. measured RD costs), and valid values. For multi-level numeric speed features, document each numeric level with its exact evaluation conditions, which stages or calculations are skipped (e.g., start MV vs. final MV checks), and any fallback or redo behavior.

Why. Vague comments like ‘adjust the RC’ or underspecified level summaries obscure algorithmic differences, evaluation timing, fallback re-searches, and pipeline stage constraints. Clear and comprehensive comments enable maintainers to safely tune, debug, and understand speed/quality tradeoffs without reverse-engineering heuristic implementations across multiple files.

Examples

Bad:

// For keyframes in rtc: adjust the RC based on content.
int rc_adjust_keyframe;

// Default Transform search case - used in evaluation of best inter candidates
TX_SEARCH_DEFAULT = 0,
// Transform search in motion mode rd
TX_SEARCH_MOTION_MODE,

// 0: Do not downsample rows
// 1: Use SAD deviation of the even rows to odd rows as the metric to
//    downsample rows
// 2: Downsample rows
int use_downsampled_sad;

Good:

// For keyframes in rtc: adjust the rc_bits_per_mb, to reduce overshoot.
int rc_adjust_keyframe;

// Default transform search used in evaluation of best inter candidates
// (MODE_EVAL stage) and motion mode winner processing (WINNER_MODE_EVAL stage).
TX_SEARCH_DEFAULT = 0,
// Transform search in motion mode rd during MODE_EVAL stage.
TX_SEARCH_MOTION_MODE,

// 0: Disabled (do not downsample rows)
// 1: Skip SAD calculation of odd rows if SAD deviation for start MV is small.
//    Redo motion search with sf off when SAD deviation is high for final MV.
// 2: Skip SAD calculation of odd rows without start MV testing.
int use_downsampled_sad;