[Code Quality] Increase inline comment density across compiler files

[github-actions]

Description

Compiler files in pkg/workflow/ have low comment density (3-5%), well below the ideal 10-20% range. While the code is well-structured, complex algorithms and security-critical sections lack inline documentation explaining the "why" behind implementation decisions.

Current State

File	Comment Density	Target	Gap
compiler.go	3.3%	10-15%	-7%
compiler_yaml.go	3.9%	10-15%	-6%
compiler_activation_jobs.go	20.7%	10-15%	✅ Good

Average: 9.3% (below 10% minimum)

Areas Needing Comments

Priority 1: Security-Critical Sections

• ANSI escape code stripping (compiler_yaml.go lines 54-55, 67-68, 80-81)

  • Why: Prevents terminal color codes from breaking YAML parsing
  • Add: Security rationale and attack scenarios prevented

• Expression extraction and wrapping (compiler_yaml.go)

  • Why: Template injection prevention
  • Add: Security context and validation rules

Priority 2: Complex Algorithms

• Chunking logic (compiler_yaml.go lines 153-182)

  • Why: Handles large prompts split across multiple steps
  • Add: Algorithm explanation and edge cases

• Validation pipeline (compiler.go lines 55-176)

  • Why: 15+ validation phases with dependencies
  • Add: Validation order rationale and interdependencies

Priority 3: Non-Obvious Implementation Decisions

• Path sanitization (compiler.go line 98)

  • Why: Prevents path traversal attacks
  • Add: Security context

• Performance optimizations (string builder pre-allocation)

  • Why: Reduces memory allocations
  • Add: Performance rationale and benchmarks

Suggested Improvements

Before (Missing Context)

// Line 49 in compiler_yaml.go
description = stringutil.StripANSIEscapeCodes(description)

After (Clear Context)

// Security: Strip ANSI escape codes to prevent YAML parsing errors
// and potential terminal injection attacks. These codes can be accidentally
// introduced via colored terminal output or malicious input.
// See: scratchpad/yaml-version-gotchas.md for YAML security details
description = stringutil.StripANSIEscapeCodes(description)

Example for Complex Logic

// Chunking algorithm for large prompts (lines 153-182)
//
// Problem: GitHub Actions has a ~21KB limit on workflow step inputs.
// Solution: Split large prompts into multiple sequential steps, each under 20.9KB.
//
// Algorithm:
// 1. Measure total prompt size including overhead (headers, footers)
// 2. If under 20.9KB, use single step
// 3. If over 21KB, split at logical boundaries (newlines, sentences)
// 4. Distribute chunks to maintain context between steps
//
// Edge cases:
// - Single line exceeding 21KB: Hard error (unsupported)
// - Markdown code blocks: Split at block boundaries to preserve syntax
// - Multi-byte UTF-8: Split at character boundaries, not bytes
func splitContentIntoChunks(content string, maxSize int) ([]string, error) {
    // ... implementation ...
}

Files Affected

Focus on these high-impact files:

• pkg/workflow/compiler.go (661 lines, 3.3% comments)
• pkg/workflow/compiler_yaml.go (510 lines, 3.9% comments)
• pkg/workflow/compiler_yaml_main_job.go (612 lines, 22.5% comments - already good)

Success Criteria

• Comment density increased to 10-15% in target files
• All security-critical sections have clear security rationale comments
• Complex algorithms have algorithm explanation comments (purpose, approach, edge cases)
• Non-obvious implementation decisions have "why" comments
• Comments focus on "why" and "what" (not "how" - code shows how)
• Comments are clear, concise, and add value (no obvious comments)

Impact

• Onboarding: New contributors understand code faster
• Maintenance: Reduces time to understand complex sections
• Security: Security-critical code is clearly marked and explained
• Effort: 1-2 hours per file estimated (3-6 hours total)
• Priority: Medium - Improves long-term maintainability

Source

Extracted from:

• Daily Compiler Code Quality Report - 2026-02-03 discussion #13521
• Daily Compiler Code Quality Report - 2026-01-28 discussion #12164

Quotes from source:

"Comment Density: 3.3% (Target: 10-20%). Limited comment coverage indicates opportunity to improve inline documentation."

"Add inline comments for security-critical sections (ANSI stripping, expression extraction)"

Priority

Medium - Improves maintainability and onboarding, not blocking

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 18, 2026, 5:21 AM UTC