Code Qualities Assessment

Code Qualities Assessment

Evaluate code maintainability using 5 timeless design qualities with quantifiable scoring rubrics.

Triggers

• assess code quality
• evaluate maintainability
• check code qualities
• testability review
• run quality assessment

Quick Start

# Assess a single file
python3 scripts/assess.py --target src/services/auth.py

# Assess changed files only (CI mode)
python3 scripts/assess.py --target . --changed-only --format json

# Full module assessment with HTML report
python3 scripts/assess.py --target src/services/ --format html --output quality-report.html

The 5 Code Qualities

When to Use

Use this skill when:

• Reviewing code quality before merge
• Identifying refactoring priorities
• Establishing quality baselines
• Teaching code design principles
• Tracking quality trends over time
• Enforcing quality gates in CI

Use analyze instead when:

• Performing broad codebase investigation
• Security assessment is the focus
• Architecture review is needed

Process

The skill runs automated assessment via scripts/assess.py:

1. Symbol Extraction

   • Detect language
   • Use Serena (if available)
   • Extract classes/methods

2. Quality Scoring

   • Run 5 quality assessments
   • Apply context rules (test vs prod)
   • Aggregate symbol -> file -> module

3. Comparison (if historical data)

   • Load previous scores
   • Identify regressions/improvements

4. Report Generation

   • Format: markdown, JSON, or HTML
   • Include remediation guidance
   • Link to refactoring patterns

5. Gate Enforcement (CI mode)

   • Check thresholds
   • Exit code: 0=pass, 10=degraded

Command Reference

Basic Usage

python3 scripts/assess.py --target <path> [options]

Parameters

Exit Codes

Configuration

Create .qualityrc.json to customize thresholds:

{
  "thresholds": {
    "cohesion": { "min": 7, "warn": 5 },
    "coupling": { "max": 3, "warn": 5 },
    "encapsulation": { "min": 7, "warn": 5 },
    "testability": { "min": 6, "warn": 4 },
    "nonRedundancy": { "min": 8, "warn": 6 }
  },
  "context": {
    "test": {
      "testability": { "min": 3 }
    }
  },
  "ignore": [
    "**/generated/**",
    "**/*.pb.py",
    "**/migrations/**"
  ]
}

Anti-Patterns

Verification

After running assessment:

• All 5 qualities scored for each symbol
• Scores are 1-10 (not null or out of range)
• Remediation links provided for low scores
• Report format is valid (markdown/JSON/HTML)
• Exit code matches assessment result
• Historical data saved to .quality-cache/

Cohesion

How strongly related are responsibilities within a boundary?

High cohesion = focused, understandable code. Low cohesion = "god objects" doing too much.

Coupling

How dependent is this code on other code?

Loose coupling = independent evolution, easy testing. Tight coupling = fragile, hard to test.

Encapsulation

How well are implementation details hidden?

Good encapsulation = freedom to change internals. Poor encapsulation = brittle API.

Testability

How easily can behavior be verified in isolation?

Testable code = fast feedback, confidence to refactor. Untestable code = fear of change.

Non-Redundancy

How unique is each piece of knowledge?

DRY code = fix once, single source of truth. Duplication = fix N times, maintenance burden.

Example 1: Single File Assessment

python3 scripts/assess.py --target src/models/user.py

Output:

# Code Quality Assessment: src/models/user.py

## Summary
- **Cohesion**: 8/10
- **Coupling**: 4/10 (warning)
- **Encapsulation**: 9/10
- **Testability**: 7/10
- **Non-Redundancy**: 9/10

## Issues Found

### Coupling: 4/10 (Warning)
**Problem**: Direct instantiation of DatabaseConnection in constructor

**Impact**: Hard to test, tightly coupled to database layer

**Remediation**: Use dependency injection
- See: [Dependency Injection](references/patterns/dependency-injection.md)
- Related ADR: ADR-023 (Dependency Management)

Example Fix:

# Before
class User:
    def __init__(self):
        self.db = DatabaseConnection()  # Hard-coded dependency

# After
class User:
    def __init__(self, db: DatabaseInterface):
        self.db = db  # Injected dependency

Example 2: CI Integration

# In CI pipeline
python3 scripts/assess.py --target . --changed-only --format json --output quality.json

# Exit code 10 = quality degraded, fail PR
# Exit code 0 = quality maintained, pass

Example 3: Full Codebase Report

python3 scripts/assess.py --target src/ --format html --output reports/quality.html

Opens dashboard showing:

• Quality trends over time
• Hot spots (lowest scoring files)
• Improvement opportunities
• Top refactoring priorities

With planner

# Identify refactoring targets
python3 scripts/assess.py --target src/ --format json | \
  jq '.files | sort_by(.overall) | .[0:5]' > low-quality-files.json

# Feed to planner
planner --input low-quality-files.json --goal "Refactor lowest quality files"

With adr-review

When reviewing ADRs, include quality impact:

# Before implementing ADR
python3 scripts/assess.py --target affected-files.txt > baseline.md

# After implementing ADR
python3 scripts/assess.py --target affected-files.txt > post-implementation.md

# Compare
diff baseline.md post-implementation.md

With analyze

Combine broad analysis with focused quality metrics:

# First: broad exploration
analyze --target src/

# Then: quality deep dive on problem areas
python3 scripts/assess.py --target src/services/auth.py

For detailed scoring methodology and examples:

• Cohesion Scoring
• Coupling Scoring
• Encapsulation Scoring
• Testability Scoring
• Non-Redundancy Scoring
• Calibration Examples
• Refactoring Patterns

Language Support

Serena integration improves accuracy when available.

Design Philosophy

This skill embodies "sergeant methods directing privates":

• Sergeant (assess.py): Orchestrates workflow, delegates to specialists
• Privates (score_*.py): Focus on one quality each, report back

Each quality scorer is cohesive (single responsibility), loosely coupled (independent), and testable (pure calculation).

Timelessness: 9/10

These 5 qualities are computer science fundamentals:

• Cohesion and coupling: 1970s (Parnas, Stevens)
• Encapsulation: Core OOP principle (1960s)
• Testability: TDD movement (1990s-2000s)
• DRY: Pragmatic Programmer (1999)

Language-agnostic design ensures longevity across technology shifts.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.