Why does EK9 report on readability?

← Code Quality · Ref: Q320

EK9 calculates an Automated Readability Index (ARI) score for each source file and reports it in the quality dashboard. This is informational only, NOT a compilation error.

ARI SCORES

The ARI score estimates the reading level needed to understand a file. It is a purely lexical measure over every token in the file (keywords and literals count too): it uses the average number of letters per token and the number of tokens per statement. It does no camelCase splitting and counts no syllables. Scores are capped at 20, and lower scores mean more readable code.

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. There is one 'Readability (ARI)' value per file in the file metrics section, not one per function or class.

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, one score per file shown in HTML dashboard, informational metric for continuous improvement.

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