DEV Community

Rasika Dangamuwa
Rasika Dangamuwa

Posted on

Why Your Readability Score Is Lying to You (And How Word Counting Breaks in Code)

#webdev #programming #productivity #javascript

Ever added estimated reading times to your documentation site or technical blog, only to notice that a 200-word tutorial on configuring nginx.conf is flagged as an "8-minute read with 12th-grade reading difficulty"?

Readability algorithms like Flesch-Kincaid, Gunning Fog, and Coleman-Liau were designed in the mid-20th century to evaluate printed prose, school textbooks, and news articles. When applied to modern technical writing—packed with inline code snippets (curl -X POST), hyphenated CLI flags (--no-preserve-root), snake_case identifiers (user_auth_token), and JSON payloads—these legacy formulas fail catastrophically.

If you rely on automated content checks or build developer documentation pipelines, understanding why word-counting and readability heuristics break is essential for accurate analytics.

The Flawed Math Behind Readability Scores

The most common readability metric used by content tools is the Flesch Reading Ease formula:

$$\text{Score} = 206.835 - 1.015 \left( \frac{\text{Total Words}}{\text{Total Sentences}} \right) - 84.6 \left( \frac{\text{Total Syllables}}{\text{Total Words}} \right)$$

The formula relies heavily on two metrics: average sentence length and average syllables per word. In standard English prose, longer words typically correlate with higher vocabulary complexity.

In software engineering prose, however:

  1. Technical Jargon Distorts Syllable Counts: Heuristic syllable counters rely on vowel-group parsing. Terms like async (2 syllables), gRPC (4 syllables), or Kubernetes (4 syllables) are treated as excessively complex words, penalizing clarity scores even when the explanation is simple.
  2. Code Blocks Destroy Sentence Boundaries: Periods used in method calls (db.user.find()), file extensions (config.prod.json), or IP addresses (127.0.0.1) fool naive sentence splitters into treating single lines of code as dozens of ultra-short sentences.

Regex Edge Cases: How Naive Word Counting Fails

Most simple word counter implementations in frontend apps rely on naive whitespace splitting:

// Naive word counter (breaks easily)
function countWordsNaive(text) {
  if (!text.trim()) return 0;
  return text.trim().split(/\s+/).length;
}

console.log(countWordsNaive("user-first, API-driven design.")); // Output: 3 words
console.log(countWordsNaive("const [state, setState] = useState(null);")); // Output: 5 words
Enter fullscreen mode Exit fullscreen mode

While split(/\s+/) works for basic paragraphs, it creates significant errors when processing technical Markdown:

  • Hyphenated Identifiers: k8s-cluster-autoscaler is counted as 1 word by whitespace splitters, but 3 words by regex word-boundary splitters (/\b\w+\b/).
  • Code Blocks: A 50-line TypeScript interface definition might contain 150 syntactical tokens that represent zero actual prose words.
  • Unicode & Emoji: Internationalized text or unicode symbols like grapheme clusters break standard byte or character length splits.

A robust client-side word counting implementation should first strip Markdown code blocks before evaluating readability:

/**
 * Strips code blocks and calculates actual prose word count
 * @param {string} markdownText 
 * @returns {number}
 */
function getProseWordCount(markdownText) {
  // Remove fenced code blocks (```
{% endraw %}
code
{% raw %}
```) and inline code (`code`)
  const proseOnly = markdownText
    .replace(/```
{% endraw %}
[\s\S]*?
{% raw %}
```/g, '')
    .replace(/`[^`]+`/g, '');

  // Match word boundaries handling contractions correctly
  const words = proseOnly.match(/\b[A-Za-z0-9]+(?:'[A-Za-z0-9]+)?\b/g);
  return words ? words.length : 0;
}

const sample = "Check out `api.v1.users.get()` for details. It's fast!";
console.log("Prose Words:", getProseWordCount(sample)); // Output: 7 words
Enter fullscreen mode Exit fullscreen mode

Practical Audits for Developers

When auditing documentation before publishing, rely on browser-based tools that handle text stripping accurately. For quick sanity checks on articles, release notes, or README files, the Nutilz Word Counter provides real-time word, character, and line counts entirely client-side without sending text payloads to external servers.

Key Takeaways for Technical Writers

  1. Pre-process Markdown before calculating metrics: Always strip fenced code blocks and inline backtick tokens prior to running sentence or syllable counts.
  2. Don't target arbitrary readability scores for code docs: A low Flesch score on a technical API reference is normal due to domain-specific terminology.
  3. Use accurate client-side tooling: Rely on privacy-focused browser utilities like nutilz.com/word-counter to audit prose metrics quickly without server overhead.

Top comments (0)