Why does EK9 report on readability?

← Code Quality · Ref: Q320

EK9 calculates Automated Readability Index (ARI) scores for identifiers and reports them in quality dashboards. This is informational only, NOT a compilation error.

ARI SCORES

The ARI score estimates the reading level needed to understand an identifier. Scores range from 1 (simple, short names) to 20+ (very long, complex names). Lower scores mean more readable code. The score considers identifier length, word count (from camelCase splitting), and syllable complexity.

WHY INFORMATIONAL ONLY

Some domains require long identifiers. Finance has 'annualisedPercentageRate'. Chemistry has 'dihydrogenMonoxide'. Medical software has 'electrocardiogramResult'. Enforcing short names in these domains would reduce clarity, not improve it. So EK9 reports the score but does not reject high-scoring code.

WHERE SCORES APPEAR

ARI scores are visible in the -t6 HTML quality dashboard. Each function and class shows its average identifier readability. Module-level summaries highlight areas where naming could be simplified.

HELPS HUMANS AND AI

Readable identifiers benefit both human developers and AI assistants. For humans, clearer names reduce cognitive load. For AI, descriptive names mean fewer tokens needed to understand context, leading to more accurate code suggestions.

See Q311 for the full quality checks catalog. See Q290 for variable naming rules. See Q321 for the quality report dashboard.

Example

defines module qa.codequality.readability

  defines function

    <?-
      Short, descriptive names score well on readability.
      'age' is better than 'currentAgeOfTheUserInYears'.
    -?>
    isAdult() as pure
      -> age as Integer
      <- rtn as Boolean: false

      legalAge <- 18
      if age >= legalAge
        rtn: true

    <?-
      Domain-specific names are acceptable even when longer.
      'interestRate' is clear in a financial context.
    -?>
    calculateInterest() as pure
      ->
        principal as Float
        interestRate as Float
        years as Integer
      <-
        totalInterest as Float: 0.0

      annualInterest <- principal * interestRate
      totalInterest: annualInterest * years

  defines program

    ReadabilityScoresDemo()
      stdout <- Stdout()

      customerAge <- 25
      adultStatus <- isAdult(customerAge)
      stdout.println(`Adult: ${adultStatus}`)

      loanAmount <- 10000.0
      annualRate <- 0.05
      loanYears <- 3
      interest <- calculateInterest(loanAmount, annualRate, loanYears)
      stdout.println(`Interest over ${loanYears} years: ${interest}`)

Common mistakes

E11064 — Using a raw literal 18 in a comparison is a magic literal. Extract it into a named constant that documents the intent. See ek9 -h E11064 for details.

Incorrect:

if age >= 18

Correct:

legalAge <- 18
      if age >= legalAge

Coming from another language?

Java: no readability scoring in any standard tool. SonarQube measures cognitive complexity but not identifier readability. Rust: no readability scoring. Go: no readability scoring, though short names are a cultural convention. Python: no readability scoring, PEP 8 has length guidelines only. C++: no readability scoring. EK9: ARI readability scoring calculated automatically, shown in HTML dashboard, informational metric for continuous improvement.

Keywords: cognitive, dashboard, naming, quality, ARI, clean-code, readability, metric, score, identifier, readable, informational