code-scoring

Code Scoring

Systematic, quantitative code quality assessment using weighted categories and standardized deductions.

Quick Start

Full code review with score:

Score this code on a 1-10 scale using the code-scoring rubric

Category-specific assessment:

Evaluate the error handling in this module using the scoring rubric

Compare implementations:

Score both implementations and recommend which is better

Scoring Methodology

The Formula

Final Score = 10 - Total Deductions

Where:
Total Deductions = SUM(Category Deductions * Category Weight)
Category Deduction = SUM(Issue Points * Severity Multiplier)

Category Weights

Category	Weight	Focus Areas
Organization	12%	File structure, module boundaries, separation of concerns
Naming	10%	Variables, functions, classes, constants, files
Error Handling	12%	Try/catch, validation, error propagation, recovery
Testing	12%	Coverage, quality, edge cases, maintainability
Performance	10%	Efficiency, resource usage, scalability
Security	12%	Input validation, auth, data protection, secrets
Documentation	8%	Comments, API docs, README, inline explanations
SOLID Principles	10%	SRP, OCP, LSP, ISP, DIP adherence
Dependencies	6%	Version management, minimal deps, no circular refs
Maintainability	8%	Readability, complexity, changeability

Total: 100%

Severity Multipliers

Severity	Multiplier	Description
Critical	2.0x	Security vulnerabilities, data loss risks, crashes
Major	1.5x	Significant bugs, poor patterns, missing core functionality
Minor	1.0x	Code smells, style issues, minor inefficiencies
Nitpick	0.5x	Preferences, optional improvements

---

Quick Scoring Cheat Sheet

Score	Label	Meaning	Typical Characteristics
10	Exemplary	Production excellence	Minimal issues, well-tested, secure, documented
9	Excellent	Minor polish needed	1-2 nitpicks, strong overall quality
8	Very Good	Ready with small fixes	Few minor issues, solid fundamentals
7	Good	Acceptable quality	Some improvements needed, no major issues
6	Satisfactory	Functional but rough	Multiple minor issues, needs cleanup
5	Adequate	Meets minimum bar	Works but has clear problems
4	Below Average	Needs significant work	Major issues present, risky to deploy
3	Poor	Substantial rework	Multiple major issues, architectural problems
2	Very Poor	Fundamental problems	Barely functional, serious concerns
1	Critical	Do not deploy	Security vulnerabilities, crashes, data risks

---

Common Deductions Table

Quick reference for frequent issues. See references/deduction-catalog.md for complete list.

High-Impact Deductions

Issue	Base Points	Category
SQL injection vulnerability	2.0	Security
Hardcoded secrets/credentials	2.0	Security
No error handling in critical path	1.5	Error Handling
Missing input validation	1.5	Security
No tests for core functionality	1.5	Testing
N+1 query pattern	1.5	Performance
God class (500+ lines)	1.5	Organization

Medium-Impact Deductions

Issue	Base Points	Category
Inconsistent naming convention	1.0	Naming
Missing JSDoc/docstrings on public API	1.0	Documentation
Circular dependency	1.0	Dependencies
Deeply nested code (4+ levels)	1.0	Maintainability
Magic numbers without constants	1.0	Naming
Empty catch blocks	1.0	Error Handling
Duplicated code blocks	1.0	Organization

Low-Impact Deductions

Issue	Base Points	Category
Inconsistent formatting	0.5	Maintainability
Missing edge case tests	0.5	Testing
Verbose variable names	0.5	Naming
Outdated dependencies (no CVEs)	0.5	Dependencies
Missing inline comments in complex logic	0.5	Documentation

---

Scoring Workflow

Step 1: Initial Scan

1. Count lines of code
2. Identify file/module structure
3. Note language and framework
4. Check for tests presence
5. Scan for obvious red flags

Step 2: Category Assessment

For each of the 10 categories:

1. Review relevant code sections
2. Identify issues
3. Classify severity (critical/major/minor/nitpick)
4. Calculate: Issues * Severity Multiplier
5. Apply category weight

Step 3: Calculate Final Score

Final Score = 10 - (Sum of weighted deductions)

If score < 1: score = 1
If score > 10: score = 10

Step 4: Generate Report

## Code Score: X.X/10

### Score Breakdown
| Category | Weight | Deductions | Weighted |
|----------|--------|------------|----------|
| Organization | 12% | ... | ... |
| ... | ... | ... | ... |

### Critical Issues (Fix Immediately)
- [Issue 1]

### Major Issues (Fix Before Merge)
- [Issue 1]

### Minor Issues (Fix When Convenient)
- [Issue 1]

### Recommendations
- [Improvement 1]

---

Category Quick Guides

Organization (12%)

Excellent (0 deductions):

• Clear module boundaries
• Single responsibility per file
• Logical folder structure
• No circular dependencies

Red flags:

• Files > 500 lines: -1.0
• Mixed concerns in module: -1.0
• No clear structure: -1.5
• Circular dependencies: -1.0

Naming (10%)

Excellent (0 deductions):

• Descriptive, intention-revealing names
• Consistent convention (camelCase, snake_case)
• Domain terminology used correctly
• Acronyms handled consistently

Red flags:

• Single-letter variables (non-loop): -0.5
• Misleading names: -1.0
• Inconsistent convention: -1.0
• Magic numbers: -1.0

Error Handling (12%)

Excellent (0 deductions):

• All external calls wrapped
• Specific error types used
• Errors logged with context
• Graceful degradation where appropriate

Red flags:

• Empty catch blocks: -1.0
• Generic catch-all: -0.5
• Missing validation: -1.5
• Swallowed errors: -1.0

Testing (12%)

Excellent (0 deductions):

• 80%+ coverage on critical paths
• Unit, integration, and E2E tests
• Edge cases covered
• Tests are maintainable

Red flags:

• No tests: -2.0
• Only happy path: -1.0
• Flaky tests: -1.0
• Test code duplication: -0.5

Performance (10%)

Excellent (0 deductions):

• Efficient algorithms
• Appropriate caching
• No memory leaks
• Optimized queries

Red flags:

• N+1 queries: -1.5
• Blocking operations in hot path: -1.0
• Memory leaks: -1.5
• No pagination on lists: -1.0

Security (12%)

Excellent (0 deductions):

• Input validation on all boundaries
• Parameterized queries
• Secrets in environment variables
• Proper authentication/authorization

Red flags:

• SQL/command injection: -2.0
• Hardcoded secrets: -2.0
• Missing auth checks: -1.5
• XSS vulnerabilities: -1.5

Documentation (8%)

Excellent (0 deductions):

• Public API documented
• Complex logic explained
• README with setup instructions
• Changelog maintained

Red flags:

• No documentation: -1.5
• Outdated docs: -1.0
• Missing API docs: -1.0
• No README: -0.5

SOLID Principles (10%)

Excellent (0 deductions):

• Single responsibility classes
• Open for extension, closed for modification
• Proper abstractions
• Dependency injection used

Red flags:

• God classes: -1.5
• Tight coupling: -1.0
• Violation of LSP: -1.0
• Concrete dependencies: -0.5

Dependencies (6%)

Excellent (0 deductions):

• Minimal dependencies
• Locked versions
• No vulnerabilities
• Clear dependency boundaries

Red flags:

• CVE vulnerabilities: -2.0
• Circular dependencies: -1.0
• Excessive dependencies: -0.5
• Unlocked versions: -0.5

Maintainability (8%)

Excellent (0 deductions):

• Low cyclomatic complexity
• DRY principle followed
• Consistent style
• Easy to understand

Red flags:

• Cyclomatic complexity > 15: -1.0
• Duplicated code: -1.0
• Deep nesting (4+): -1.0
• Inconsistent style: -0.5

---

Score Interpretation Guide

Deployment Readiness

Score Range	Deployment Decision
8-10	Ready for production
7-7.9	Ready with minor fixes
5-6.9	Needs review and fixes
3-4.9	Significant rework required
1-2.9	Do not deploy

Review Actions

Score Range	Required Actions
9-10	Approve immediately
7-8.9	Approve with suggestions
5-6.9	Request changes
3-4.9	Major revision needed
1-2.9	Reject with detailed feedback

---

Reference Files

• references/scoring-rubrics.md - Detailed rubric for each category
• references/severity-weights.md - How to weight different issue types
• references/score-descriptors.md - What each score 1-10 means with examples
• references/deduction-catalog.md - Common issues and their point deductions