Code Quality Metrics in Java: SonarQube, Cyclomatic Complexity, Technical Debt & Maintainability in 2026

Code quality is not a feeling — it is a set of measurable, enforceable properties. In 2026, engineering teams that ship reliable Java microservices are the ones that have operationalized quality metrics: they track cyclomatic complexity per method, enforce coverage thresholds in CI, measure technical debt in hours, and fail builds when SonarQube quality gates are not met. This guide covers every major metric, shows you how to configure SonarQube and JaCoCo in Spring Boot, and demonstrates how to integrate quality enforcement into GitHub Actions pipelines that protect your main branch.

Table of Contents

1. Why Code Quality Metrics Matter in Production
2. The Core Quality Metrics Explained
3. Cyclomatic Complexity — Measurement & Reduction
4. Code Coverage with JaCoCo in Spring Boot
5. SonarQube Setup for Java Spring Boot Projects
6. SonarQube Quality Gates — Configuration & Enforcement
7. Technical Debt — Calculation & Remediation
8. Code Duplication — Detection & Fixes
9. Integrating Quality Gates in CI/CD (GitHub Actions)
10. Building a Quality Culture — Team Practices

// HIGH COMPLEXITY: CC = 8 — hard to test, hard to extend
@Service
public class OrderService {

    public BigDecimal calculateDiscount(Order order, Customer customer) {
        BigDecimal discount = BigDecimal.ZERO;

        if (customer.getTier() == CustomerTier.GOLD) {             // +1
            discount = discount.add(new BigDecimal("0.10"));
            if (order.getTotal().compareTo(new BigDecimal("500")) >= 0) { // +1
                discount = discount.add(new BigDecimal("0.05"));
            }
        } else if (customer.getTier() == CustomerTier.SILVER) {    // +1
            discount = discount.add(new BigDecimal("0.05"));
        }

        if (order.isFirstOrder() && customer.isNewCustomer()) {    // +1 +1
            discount = discount.add(new BigDecimal("0.15"));
        }

        if (order.hasPromoCode() && !order.isAlreadyDiscounted()) { // +1 +1
            discount = discount.add(new BigDecimal("0.08"));
        }

        return discount.min(new BigDecimal("0.30")); // cap at 30%
    }
}

// REFACTORED: CC = 2 per method — each rule is independently testable
@Service
@RequiredArgsConstructor
public class OrderDiscountService {

    private final List<DiscountRule> discountRules;

    public BigDecimal calculateDiscount(Order order, Customer customer) {
        return discountRules.stream()
            .map(rule -> rule.apply(order, customer))
            .reduce(BigDecimal.ZERO, BigDecimal::add)
            .min(new BigDecimal("0.30"));
    }
}

@FunctionalInterface
public interface DiscountRule {
    BigDecimal apply(Order order, Customer customer);
}

@Component
public class GoldTierDiscount implements DiscountRule {
    @Override
    public BigDecimal apply(Order order, Customer customer) {
        if (customer.getTier() != CustomerTier.GOLD) return BigDecimal.ZERO; // +1
        BigDecimal base = new BigDecimal("0.10");
        return order.getTotal().compareTo(new BigDecimal("500")) >= 0
            ? base.add(new BigDecimal("0.05")) : base;
    }
}

@Component
public class NewCustomerDiscount implements DiscountRule {
    @Override
    public BigDecimal apply(Order order, Customer customer) {
        return (order.isFirstOrder() && customer.isNewCustomer()) // +1
            ? new BigDecimal("0.15") : BigDecimal.ZERO;
    }
}

@Component
public class PromoCodeDiscount implements DiscountRule {
    @Override
    public BigDecimal apply(Order order, Customer customer) {
        return (order.hasPromoCode() && !order.isAlreadyDiscounted()) // +1
            ? new BigDecimal("0.08") : BigDecimal.ZERO;
    }
}

<!-- pom.xml — JaCoCo Maven Plugin configuration -->
<build>
  <plugins>
    <plugin>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-maven-plugin</artifactId>
    </plugin>

    <plugin>
      <groupId>org.jacoco</groupId>
      <artifactId>jacoco-maven-plugin</artifactId>
      <version>0.8.11</version>
      <executions>
        <!-- Instrument classes before tests run -->
        <execution>
          <id>prepare-agent</id>
          <goals><goal>prepare-agent</goal></goals>
        </execution>
        <!-- Generate HTML/XML report after tests -->
        <execution>
          <id>report</id>
          <phase>test</phase>
          <goals><goal>report</goal></goals>
        </execution>
        <!-- Enforce minimum coverage thresholds -->
        <execution>
          <id>check</id>
          <goals><goal>check</goal></goals>
          <configuration>
            <haltOnFailure>true</haltOnFailure>
            <rules>
              <rule>
                <element>BUNDLE</element>
                <limits>
                  <limit>
                    <counter>LINE</counter>
                    <value>COVEREDRATIO</value>
                    <minimum>0.80</minimum>
                  </limit>
                  <limit>
                    <counter>BRANCH</counter>
                    <value>COVEREDRATIO</value>
                    <minimum>0.70</minimum>
                  </limit>
                </limits>
              </rule>
            </rules>
            <!-- Exclude generated code, config, and DTO classes -->
            <excludes>
              <exclude>**/config/**</exclude>
              <exclude>**/dto/**</exclude>
              <exclude>**/*Application.class</exclude>
              <exclude>**/generated/**</exclude>
            </excludes>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

# Run tests + generate JaCoCo HTML report
mvn test jacoco:report

# Report location:
# target/site/jacoco/index.html

# To also enforce thresholds (fails build if below minimum):
mvn verify

public String classify(int score) {
    if (score >= 90) {          // branch: true/false
        return "Excellent";
    } else if (score >= 70) {   // branch: true/false
        return "Good";
    }
    return "Needs Improvement";
}

// Test that achieves 100% LINE coverage but only 50% BRANCH coverage:
@Test
void testClassify() {
    assertEquals("Excellent", classify(95)); // hits line 2 — true branch of first if
    assertEquals("Good",      classify(75)); // hits line 4 — true branch of second if
    // Missing: score < 70 path (false branch of second if) → "Needs Improvement"
    // Missing: score between 0-69 bypassing first if false branch
}

# docker-compose.yml
version: "3.8"
services:
  sonarqube:
    image: sonarqube:10.4-community
    container_name: sonarqube
    ports:
      - "9000:9000"
    environment:
      SONAR_JDBC_URL: jdbc:postgresql://db:5432/sonar
      SONAR_JDBC_USERNAME: sonar
      SONAR_JDBC_PASSWORD: sonar
    volumes:
      - sonarqube_data:/opt/sonarqube/data
      - sonarqube_extensions:/opt/sonarqube/extensions
      - sonarqube_logs:/opt/sonarqube/logs
    depends_on:
      - db

  db:
    image: postgres:15
    container_name: sonarqube_db
    environment:
      POSTGRES_USER: sonar
      POSTGRES_PASSWORD: sonar
      POSTGRES_DB: sonar
    volumes:
      - postgresql:/var/lib/postgresql
      - postgresql_data:/var/lib/postgresql/data

volumes:
  sonarqube_data:
  sonarqube_extensions:
  sonarqube_logs:
  postgresql:
  postgresql_data:

# sonar-project.properties
sonar.projectKey=my-spring-boot-service
sonar.projectName=My Spring Boot Service
sonar.projectVersion=1.0
sonar.sources=src/main/java
sonar.tests=src/test/java
sonar.java.binaries=target/classes
sonar.java.test.binaries=target/test-classes
sonar.coverage.jacoco.xmlReportPaths=target/site/jacoco/jacoco.xml
sonar.exclusions=**/config/**,**/dto/**,**/*Application.java,**/generated/**
sonar.test.exclusions=**/test/**
sonar.sourceEncoding=UTF-8

<!-- In pom.xml <build><plugins> section -->
<plugin>
  <groupId>org.sonarsource.scanner.maven</groupId>
  <artifactId>sonar-maven-plugin</artifactId>
  <version>3.10.0.2594</version>
</plugin>

# Run tests to generate JaCoCo XML, then push to SonarQube
mvn clean verify sonar:sonar \
  -Dsonar.host.url=http://localhost:9000 \
  -Dsonar.token=YOUR_SONAR_TOKEN

# For SonarCloud (hosted):
mvn clean verify sonar:sonar \
  -Dsonar.host.url=https://sonarcloud.io \
  -Dsonar.organization=your-org-key \
  -Dsonar.token=$SONAR_TOKEN

mvn clean verify sonar:sonar \
  -Dsonar.host.url=$SONAR_HOST_URL \
  -Dsonar.token=$SONAR_TOKEN \
  -Dsonar.qualitygate.wait=true \
  -Dsonar.qualitygate.timeout=300

// HIGH DEBT PATTERNS — each generates a code smell in SonarQube

// 1. Magic numbers (should be named constants)
if (retryCount > 3) {                    // SonarQube: "Replace 3 with a named constant"
    throw new RetryExhaustedException();
}

// 2. Empty catch block
try {
    process(event);
} catch (Exception e) {                   // SonarQube: "Add a comment or log or rethrow"
}

// 3. Unused private field
public class ReportService {
    private String lastGeneratedAt;       // SonarQube: "Remove this unused private field"

    public Report generate() { return new Report(); }
}

// 4. Mutable static field (thread-safety debt)
public class CacheService {
    public static List<String> cache = new ArrayList<>(); // SonarQube: blocker
}

// REMEDIATION — pay the debt:
private static final int MAX_RETRIES = 3;

if (retryCount > MAX_RETRIES) {
    throw new RetryExhaustedException();
}

try {
    process(event);
} catch (ProcessingException e) {
    log.error("Event processing failed for id={}", event.getId(), e);
    throw e;
}

<!-- pom.xml — PMD plugin with CPD -->
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-pmd-plugin</artifactId>
  <version>3.21.0</version>
  <configuration>
    <minimumTokens>100</minimumTokens>
    <failOnViolation>true</failOnViolation>
    <printFailingErrors>true</printFailingErrors>
    <excludes>
      <exclude>**/generated/**/*.java</exclude>
    </excludes>
  </configuration>
  <executions>
    <execution>
      <goals>
        <goal>cpd-check</goal>
      </goals>
    </execution>
  </executions>
</plugin>

// BEFORE — duplicated logic in two services

// In OrderService.java:
BigDecimal discounted = price.multiply(BigDecimal.ONE.subtract(
    discount.divide(new BigDecimal("100"), 2, RoundingMode.HALF_UP)));
if (discounted.compareTo(BigDecimal.ZERO) < 0) discounted = BigDecimal.ZERO;

// In CartService.java (identical block):
BigDecimal discounted = price.multiply(BigDecimal.ONE.subtract(
    discount.divide(new BigDecimal("100"), 2, RoundingMode.HALF_UP)));
if (discounted.compareTo(BigDecimal.ZERO) < 0) discounted = BigDecimal.ZERO;

// --------------------------------------------------
// AFTER — shared utility method

@Component
public class PricingUtils {

    public BigDecimal applyDiscount(BigDecimal price, BigDecimal discountPercent) {
        BigDecimal discounted = price.multiply(BigDecimal.ONE.subtract(
            discountPercent.divide(new BigDecimal("100"), 2, RoundingMode.HALF_UP)));
        return discounted.max(BigDecimal.ZERO);
    }
}

// Both OrderService and CartService inject PricingUtils and call:
BigDecimal discounted = pricingUtils.applyDiscount(price, discount);

# .github/workflows/quality.yml
name: Code Quality Gate

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

jobs:
  quality:
    name: Build, Test & Quality Gate
    runs-on: ubuntu-latest

    steps:
      - name: Checkout source
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Required for SonarQube blame information

      - name: Set up JDK 21
        uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'temurin'

      - name: Cache Maven dependencies
        uses: actions/cache@v4
        with:
          path: ~/.m2/repository
          key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}
          restore-keys: |
            ${{ runner.os }}-maven-

      - name: Cache SonarQube packages
        uses: actions/cache@v4
        with:
          path: ~/.sonar/cache
          key: ${{ runner.os }}-sonar
          restore-keys: ${{ runner.os }}-sonar

      - name: Run tests with JaCoCo coverage
        run: mvn clean verify -B

      - name: SonarQube analysis with quality gate check
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
        run: |
          mvn sonar:sonar \
            -Dsonar.host.url=https://sonarcloud.io \
            -Dsonar.organization=${{ vars.SONAR_ORG }} \
            -Dsonar.projectKey=${{ vars.SONAR_PROJECT_KEY }} \
            -Dsonar.token=${{ secrets.SONAR_TOKEN }} \
            -Dsonar.qualitygate.wait=true \
            -Dsonar.qualitygate.timeout=300 \
            -B

      - name: Upload JaCoCo report as artifact
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: jacoco-report
          path: target/site/jacoco/
          retention-days: 7

# .github/pull_request_template.md

## Code Quality Checklist
- [ ] SonarQube quality gate is green
- [ ] New code coverage ≥ 80% (check JaCoCo report)
- [ ] No methods with cyclomatic complexity > 10 introduced
- [ ] No code duplication blocks introduced (> 10 lines)
- [ ] No hardcoded credentials, magic numbers, or TODO left
- [ ] Exception handling: no empty catch blocks
- [ ] All new public methods have meaningful names (no abbreviations)
- [ ] Logging: no sensitive data in log messages

Leave a Comment

Related Posts