Skip to main content

Static Code Analysis Overview

Purpose​

Static code analysis tools help maintain code quality by automatically detecting bugs, style violations, and potential issues at compile-time or during the build process. This section documents our gradual adoption of static analysis tools.

Adoption Strategy​

We follow a "Fix Forward, Not Backward" approach:

  • ✅ Only analyze and fix code you're actively working on
  • ✅ Start with warnings, graduate to errors
  • ✅ One tool at a time
  • ✅ Measure progress incrementally

See GitHub Issue #203 for the complete adoption plan.

Integrated Tools​

✅ Phase 1: Error Prone (COMPLETE - Strict Mode)​

Status: ✅ Active in STRICT mode - builds fail on violations
Purpose: Catches common Java programming mistakes at compile-time
Documentation: 01-error-prone.md

Bugs Fixed: 13 bugs (8 from Issue #234 + 5 additional)
Result: Clean codebase, strict enforcement active

✅ Phase 2: Git Hooks (COMPLETE)​

Status: ✅ Active with flexible install/uninstall
Purpose: Automated checks before/after commits
Documentation: ../../02-developer-playbooks/08-git-hooks.md

Hooks Available:

  • Pre-commit: Error Prone on staged Java files (blocks bad commits)
  • Post-commit: Wiki sync and deploy (auto-updates documentation)

✅ Phase 2.5: Spotless (COMPLETE - Auto-Formatting)​

Status: ✅ Active - auto-formats Java code to Google Java Style Guide
Purpose: Automatically fixes formatting violations (indentation, imports, spacing)
Documentation: 02-checkstyle-spotless.md

Achievement: 149+ files formatted across entire codebase in one operation
Impact: Eliminated hundreds of formatting violations automatically

✅ Phase 3: Checkstyle (COMPLETE - Warning Mode)​

Status: ✅ Active in WARNING mode - violations logged, builds succeed
Purpose: Validates compliance with Google Java Style Guide (documentation, naming, etc.)
Documentation: 02-checkstyle-spotless.md

Current State: Only non-formatting violations remain (Javadoc, method ordering, etc.)
Next: Graduate to strict mode after documentation baseline is improved

🔜 Phase 4: JaCoCo (Planned)​

Purpose: Test coverage measurement and enforcement
Timeline: After Checkstyle graduates to strict mode
Mode: Report-only initially, then enforce minimum thresholds

🔜 Phase 5: PMD (Planned)​

Purpose: Detects unused code, complexity issues, and code smells
Timeline: After coverage baseline is established
Mode: Minimal ruleset initially

🔜 Phase 6: SpotBugs (Future)​

Purpose: Additional bug detection complementary to Error Prone
Timeline: TBD based on needs

Quick Start​

Running Analysis Locally​

# Run all enabled static analysis tools
export JAVA_HOME=/usr/lib/jvm/temurin-23-jdk-arm64
mvn clean compile

# Auto-format code
mvn spotless:apply      # Format all files
mvn spotless:check      # Check formatting only

# Validate style compliance  
mvn checkstyle:check    # Style validation

# Future tools (when more are added)
mvn pmd:check           # PMD analysis
mvn jacoco:report       # Coverage report

Understanding Results​

Each tool provides links to detailed explanations:

Fixing Issues Incrementally​

  1. Work on a feature/bugfix as normal
  2. Run mvn compile to see warnings for files you're modifying
  3. Fix warnings in those files as part of your changeset
  4. Commit with improved code quality

Don't try to fix the entire codebase at once!

CI/CD Integration​

Current State​

  • ✅ Local builds run Error Prone
  • 🔜 GitHub Actions workflow (Phase 6)
  • 🔜 Pre-commit hooks (Phase 7)

Future State​

Once all tools are stable:

# .github/workflows/code-quality.yml
name: Code Quality

on: [pull_request, push]

jobs:
  static-analysis:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          java-version: '23'
          distribution: 'temurin'
      - name: Run Static Analysis
        run: mvn clean compile checkstyle:check pmd:check
      - name: Run Tests with Coverage
        run: mvn test jacoco:report

Configuration Files​

All static analysis tools are configured in:

  • Maven Configuration: pom.xml (plugin configurations)
  • Checkstyle Rules: config/checkstyle/google_checks.xml (when added)
  • PMD Rules: config/pmd/ruleset.xml (when added)
  • Error Prone: Inline in maven-compiler-plugin

Metrics & Progress​

Current Baseline​

  • Error Prone Issues: 8 (as of Oct 2025)
    • ImpossibleNullComparison: 7
    • SelfAssignment: 1

Goals​

  • Month 1: Error Prone issues resolved, strict mode enabled
  • Month 2: Checkstyle enforced on new code
  • Month 3: 60% test coverage baseline
  • Month 4: PMD running on all code
  • Month 5: All tools in strict mode

Suppressing False Positives​

Sometimes static analysis tools report false positives. When suppressing warnings:

  1. Use tool-specific annotations:

    @SuppressWarnings("ErrorProneBugPattern")
    @SuppressLint("PMD.UnusedPrivateMethod")

  2. Always add justification:

    @SuppressWarnings("ImpossibleNullComparison")
    // Justification: Framework injects null during initialization phase
    public void myMethod() { ... }

  3. Make it specific (per-method, not per-class)

  4. Document in code review why suppression is necessary

Best Practices​

For Developers​

  1. Run mvn compile frequently during development
  2. Fix warnings in files you're modifying before committing
  3. Don't ignore warnings - they often indicate real bugs
  4. Ask for help if a warning seems wrong or unclear

For Code Reviewers​

  1. Check that new code has no warnings (once strict mode is enabled)
  2. Question suppressed warnings - are they justified?
  3. Ensure documentation is updated when adding new checks
  4. Encourage incremental fixes in legacy code

Documentation Index​

  • 01-error-prone.md - Error Prone integration guide
  • 02-checkstyle-spotless.md - Checkstyle validation and Spotless auto-formatting
  • 03-jacoco.md (Coming soon) - Test coverage with JaCoCo
  • 04-pmd.md (Coming soon) - PMD code quality checks
  • 05-integration.md (Coming soon) - CI/CD integration guide

Resources​

Official Documentation​

Style Guides​

FAQ​

Q: Do I need to run these tools manually?​

A: No, they run automatically during mvn compile. You'll see warnings in your terminal.

Q: Can static analysis catch all bugs?​

A: No, but it catches many common mistakes. You still need tests, code reviews, and good engineering practices.

Q: What if the build time increases significantly?​

A: We've measured ~10-15% increase with Error Prone. This is acceptable for the bugs it catches. If other tools add too much overhead, we'll optimize.

Q: Should I fix warnings in files I'm not modifying?​

A: Generally no - focus on files you're actively working on. Exception: if you're doing a focused cleanup effort.

Q: What takes priority - tests or static analysis?​

A: Both are important. Fix obvious bugs from static analysis, then ensure tests pass. Don't disable analysis to make tests pass.

Contributing​

When adding new static analysis tools:

  1. Follow the phased approach outlined in Issue #203
  2. Start in warning mode to avoid breaking the build
  3. Document the tool in this section
  4. Update this overview with current status
  5. Add configuration examples and common issues
  6. Measure impact on build time and developer workflow