Explore

Project Health Scoring Manual

Date: 2025-06-03

Table of Contents

Overview

Dimension 1 – UI/UX Quality (15 %)

Dimension 2 – Defect Management (40 %)

Dimension 3 – Maintainability, Security & Technical Debt (Codacy combined, 45 %)

Global Score Calculation

Thresholds & Recommended Actions

Minimal Implementation

⁠

Section 1 – Overview

This manual provides an objective framework for measuring a software project’s technical health on a 0–100 scale, regardless of its implementation phase. It covers three critical dimensions:

Defect Management – 40 %

Maintainability, Security & Technical Debt (Codacy combined) – 45 %

UI/UX Quality – 15 %

Each dimension is scored from 0 to 1 and then multiplied by its respective weight. The final score is the weighted sum, expressed as a percentage (0 = minimal technical health, 100 = optimal).

Primary Goals

Reduce customer complaints and loss of trust by catching and fixing critical issues swiftly.

Ensure a stable, secure, and sustainable codebase over time.

Deliver a “premium” user interface and experience that maximizes perceived quality, engagement, and value.

Below, each dimension is detailed with its evaluation criteria.

⁠

Section 2 – Dimension 1: UI/UX Quality (15 %)

Objective: Ensure the interface and user experience meet premium standards—modern, brand-coherent, and highly engaging—at any stage of development.

2.1. Evaluation Criteria

Brand Alignment & Visual Style (20 %)

Color Palette: Consistent use of brand colors across screens and interactive elements.

Typography & Text Hierarchy: Uniform font choices; clear differentiation between headings, subheadings, and body text.

Brand Assets: Logo, iconography, and distinctive styles (e.g., button shapes, corner radius, shadows) applied consistently throughout the app.

Information Architecture & User Flow (20 %)

Clear Visual Hierarchy: Headings and calls to action (CTAs) prioritized with adequate contrast and spacing.

Intuitive Navigation: Menus, navigation bars, and pathways designed so users complete tasks in as few steps as possible.

Interactivity & Immediate Feedback (15 %)

Subtle Animations: Smooth transitions on buttons and microinteractions on hover/tap to reinforce actions.

Loading/Status Indicators: Spinners, progress bars, or contextual messages to inform users of background processes (data fetch, form submission).

Input Feedback: Real-time form validations, clear error messages, and actionable suggestions.

Responsiveness (15 %)

Multi-Platform Adaptation: Responsive design that looks and works properly on mobile, tablet, and desktop with defined breakpoints.

Accessibility & Universal Usability (15 %)

Color Contrast: Minimum WCAG AA compliance (4.5:1 contrast ratio) for text and interactive elements.

Keyboard Navigation Support: All controls must be accessible without a mouse, with a visible focus indicator.

Innovation & Modernity (15 %)

Contemporary UI Patterns: Use of card-based layouts, microinteractions, and emerging design components (e.g., moderate neumorphism or glassmorphism if relevant).

Value-Added Features: Optional dark mode, touch gestures (swipe, pinch), or AI-driven real-time recommendations.

Competitive Benchmarking: Quick comparison against similar market apps to ensure visual positioning matches industry leaders.

2.2. Subscores & Formula

Assign each criterion a subscore from 0 to 1 (1 = fully compliant, 0 = not compliant). Then calculate UXScore:

UXScore =

0.20 × BrandStyle

+ 0.20 × InformationArchitecture

+ 0.15 × Interactivity

+ 0.15 × Responsiveness

+ 0.15 × Accessibility

+ 0.15 × Innovation

BrandStyle: Percentage of brand-alignment items met.

InformationArchitecture: Score from usability tests on flows and visual hierarchy.

Interactivity: Evaluation of microinteractions and immediate feedback.

Performance: Normalized performance metric versus target.

Accessibility: Percentage of WCAG rules and keyboard navigation checks passed.

Innovation: Degree of modern UI patterns and advanced features implemented.

UXScore Range: 0 (low-quality experience) to 1 (premium experience). Multiply by 15 % to contribute to the Global Score.

⁠

Section 3 – Dimension 2: Defect Management (40 %)

Objective: Minimize the customer impact of defects and ensure that critical issues are resolved quickly to avoid escalations, loss of trust, and re-work costs.

3.1. Severity Scale (Weight W)

Table 2

Table 2

Severity

Description

Weight (W)

Critical failure (full crash, data loss)

Essential function unavailable

0.8

Partial functional impact

0.5

Visual glitch or UX issue with no functional impact

0.2

Typos, confusing copy, minor fixes

0.1

There are no rows in this table

⁠

3.2. Defect Quality Index (60 %)

Collect Data

From your issue tracker (Singular Stories), extract the number of closed defects in the period (sprint, month, or release), grouped by severity S1–S5.

Record the number of user stories delivered (N) in that same period.

Calculate RiskScore

RiskScore = Σ (W × DefectCount_S)

DefectCount_S is the total count of defects at severity level S.

Calculate QualityScore

QualityScore = 1 – (RiskScore / N)

If RiskScore / N > 1 ⇒ QualityScore is capped at 0.

Range: 0 (high volume/severity of defects) to 1 (very few or no critical defects).

3.3. Mean Time To Resolution for Critical Defects (40 %)

Calculate MTTRcrit

Only include defects of severity S1 and S2.

For each S1 or S2 defect, compute resolution hours:

HoursToResolve_i = ClosedTimestamp_i – OpenedTimestamp_i

Sum all resolution hours and divide by the total number of S1+S2 defects:

MTTRcrit = Σ(HoursToResolve_i) / (Count_S1 + Count_S2)

Define SLA_48h

The team’s target is to resolve S1 and S2 defects within 48 hours on average.

Calculate TRscore

TRscore = MAX(0; 1 – (MTTRcrit / 48))

Example: if MTTRcrit = 24 h ⇒ 1 – (24/48) = 0.5.

If MTTRcrit ≥ 48 h ⇒ TRscore = 0.

3.4. Final DefectScore Formula

DefectScore = 0.6 × QualityScore + 0.4 × TRscore

QualityScore (0–1) measures defect volume and severity relative to delivered stories.

TRscore (0–1) measures speed of correction for critical defects.

Multiply the resulting DefectScore by 40 % for the Global Score.

⁠

Section 4 – Dimension 3: Maintainability, Security & Technical Debt (Codacy combined, 45 %)

Objective: Ensure the codebase remains clean, secure, and sustainable over time, while quantifying and controlling accumulated technical debt using Codacy.

4.1. Codacy Metrics

Codacy provides these metrics on every analysis:

Quality Grade (A–F)

Overall grade based on code smells, style issues, and best practices.

GradeScore (0–1) Conversion:

A = 1.0

B = 0.8

C = 0.6

D = 0.4

E = 0.2

F = 0.0

Code Issues (Security + Error Prone) per KLOC

Number of critical or blocker vulnerabilities per 1 000 lines of code.

SecurityScore (0–1):

SecurityScore = 1 – MIN(IssuesPerKLOC, 0.5) / 0.5

If IssuesPerKLOC ≥ 0.5 ⇒ SecurityScore = 0.

If 0 ⇒ SecurityScore = 1.

Test Coverage (%)

Percent of critical code lines covered by automated tests.

CoverageScore (0–1):

CoverageScore = MIN(Coverage, 80) / 80

If coverage ≥ 80 % ⇒ CoverageScore = 1.

If 40 % ⇒ 0.5, etc.

Average Cyclomatic Complexity

Average complexity per function/method.

ComplexityScore (0–1):

ComplexityScore = 1 – MIN(AverageComplexity, 15) / 15

If complexity = 0 ⇒ 1.

If ≥ 15 ⇒ 0.

Code Duplication (%)

Percent of duplicated lines in the repository.

DuplicationScore (0–1):

DuplicationScore = 1 – MIN(Duplication, 10) / 10

If duplication = 0 ⇒ 1.

If ≥ 10 % ⇒ 0.

Total Remediation Time (Technical Debt) & KLOC

TotalRemediationTime: Sum of hours or minutes Codacy estimates for fixing all open issues.

KLOC: Number of thousands of lines of code in the project.

DebtRatio (0–1):

Define an acceptable threshold t in hours/KLOC (e.g., 2 h/KLOC).

DebtRatio = MIN(TotalRemediationTimeInHours / KLOC, t) / t

If TotalRemediationTimeInHours/KLOC ≤ t ⇒ DebtRatio < 1.

If > t ⇒ DebtRatio = 1.

DebtScore (0–1):

DebtScore = 1 – DebtRatio

If debt is 0 ⇒ DebtScore = 1.

If debt ≥ t ⇒ DebtScore = 0.

4.2. Internal Weights

Within the 45 % allocated to this dimension, assign weights to each metric:

Quality Grade: 20 %

Security Issues/KLOC: 20 %

Coverage (%): 15 %

Cyclomatic Complexity: 10 %

Duplication (%): 15 %

DebtScore: 20 %

Total internal weight = 100 %.

4.3. CombinedCodeScore Calculation (0–1)

CombinedCodeScore =

0.20 × GradeScore

+ 0.20 × SecurityScore

+ 0.15 × CoverageScore

+ 0.09 × ComplexityScore

+ 0.09 × DuplicationScore

+ 0.20 × DebtScore

The resulting CombinedCodeScore (0–1) is then multiplied by 45 % to contribute to the Global Score.

⁠

Section 5 – Global Score Calculation

Once each dimension is normalized (0–1), the TotalScore is:

TotalScore =

(UXScore × 0.15)

+ (DefectScore × 0.40)

+ (CodeScore × 0.45)

UXScore (0–1) × 15 %

DefectScore (0–1) × 40 %

CombinedCodeScore (0–1) × 45 %

The final result is between 0 and 1; multiply by 100 to present it as a percentage (0 – 100).

⁠

Section 6 – Thresholds & Recommended Actions

Table 1

Table 1

TotalScore (%)

Technical Status

Recommended Action

< 60

Critical Risk

Immediate improvement plan: assign a refactoring epic and bulk corrections.

60 – 80

Attention Required

Heightened monitoring and mitigation plan (include a technical-debt sprint and QA review).

> 80

Optimal Technical Health

Maintain current practices; perform weekly monitoring of debt and defects.

There are no rows in this table

⁠

If UXScore < 0.6: conduct a rapid interface redesign session and usability testing for key flows.

If DefectScore < 0.6: prioritize backlog review of critical bugs and affected services.

If DebtScore < 0.6: schedule a dedicated debt-reduction sprint (refactoring, test coverage, code cleanup).

If CombinedCodeScore < 0.6: initiate a gradual code freeze to consolidate quality improvements.

⁠

Want to print your doc?
This is not the way.

Try clicking the ⋯ next to your doc name or using a keyboard shortcut (

CtrlP

) instead.