Maintainability Scorer
Produce a composite maintainability score by analyzing code quality, change risk, modularity, and documentation coverage to predict the cost of future changes.
Guiding Principle
"Maintainability is not about today's code — it's about tomorrow's developer understanding it."
Procedure
Step 1 — Code Quality Index
- Measure cyclomatic and cognitive complexity per module.
- Detect code duplication percentage across the codebase.
- Assess naming quality: are names descriptive and consistent?
- Check for dead code: unused exports, unreachable branches, commented-out code.
- Score readability: function length, nesting depth, parameter count
[HECHO].
Step 2 — Change Risk Assessment
- Identify high-churn files from git history (files changed most frequently).
- Cross-reference churn with complexity (high churn + high complexity = high risk).
- Map coupling: which files always change together (logical coupling)?
- Assess test coverage on high-churn areas.
- Calculate change failure rate per module if CI history is available
[INFERENCIA].
Step 3 — Modularity Analysis
- Evaluate module boundaries: are they clean or leaky?
- Check for information hiding: are internals exposed through public APIs?
- Assess dependency direction: do dependencies point inward (good) or outward (bad)?
- Measure module cohesion: do module contents belong together?
- Identify God modules that do too many things.
Step 4 — Maintainability Report
- Compute per-module maintainability score (0-100) using weighted formula.
- Weights: complexity (25%), duplication (15%), test coverage (20%), modularity (20%), documentation (10%), naming (10%).
- Rank modules from most to least maintainable.
- Identify the 3 highest-risk modules for future changes.
Quality Criteria
- Scores based on measurable metrics, not subjective opinion
[HECHO]
- Weights explicitly stated and justified
- High-risk modules identified with specific evidence
- Change risk correlated with actual git history
Anti-Patterns
- Scoring based solely on line count or cyclomatic complexity
- Ignoring test coverage in maintainability assessment
- Treating all modules equally regardless of change frequency
- Using a single global score instead of per-module granularity