Pseudocode is a lie

2025-09-10 · Source: The Computist Journal · Field: Technology & Digital — Software Development & Engineering, Research Methodology & Innovation · Depth: Intermediate, medium

Summary

The article argues that pseudocode is ineffective for explaining algorithms, challenging its common defenses in texts like CLRS. It claims pseudocode is neither intuitive nor formal, forcing readers to translate ambiguous syntax without formal guarantees. Instead, the author advocates for a "two registers" approach: using diagrams and narrative for intuitive explanations, and real, executable code (preferably Python) for formal content. To prevent documentation and code from drifting apart, the article promotes literate programming, specifically introducing `illiterate`. This open-source Python tool extracts tagged code blocks from `.qmd` files, assembling them into runnable source files. This ensures that the documentation describes compilable algorithms, tests run against the visible code, and a working library is generated directly from the book's source, as demonstrated in `The Algorithm Codex` with examples like Quicksort.

Key takeaway

For technical authors and educators explaining algorithms, abandon pseudocode to avoid ambiguity and translation burdens. Instead, structure your content using clear diagrams for intuitive understanding and real, executable Python code for formal definitions. Consider adopting literate programming tools like `illiterate` to ensure your documentation and code remain perfectly synchronized, guaranteeing that published algorithms are always compilable and testable. This approach enhances clarity and provides readers with immediately runnable examples.

Key insights

Pseudocode is a flawed explanation tool; prioritize intuitive diagrams and formal, executable code.

Principles

• Intuition should precede formalization in explanations.
• Pseudocode lacks both genuine intuition and formal semantics.
• Real programming languages offer sufficient abstraction and portability.

Method

Explain intuitively with diagrams/narration, and formally with real code. Use literate programming tools like `illiterate` to extract executable code from documentation source files.

In practice

• Use Python for algorithm examples in technical books.
• Implement `illiterate` to build runnable libraries from book content.
• Verify algorithms via build-time execution of demo blocks.

Topics

• Literate Programming
• Algorithm Explanation
• Python Programming
• Technical Documentation
• Code Synchronization
• illiterate Tool
• Computer Science Education

Code references

• apiad/illiterate

Best for: Software Engineer, Research Scientist, AI Student

Related on AIssential

• Stop Writing Python Like This (Please) — Adopt Pythonic idioms to write cleaner, faster, and more maintainable code.
• I Spent Two Years Building a Template That AI Replaced in Seconds — Over-abstraction and static templates hinder productivity in dynamic software development, even with AI tools.
• 5 Powerful Python Decorators to Build Clean AI Code — Python decorators can significantly improve AI code cleanliness and robustness by separating core logic from boilerplate tasks.
• Structured errors to facilitate learning — Python variable naming rules balance strict syntax with broad Unicode character support.
• Comprehension Debt: The Hidden Cost of AI-Generated Code — Over-reliance on AI code generation creates "comprehension debt," reducing human understanding and increasing systemic risk.
• The Biggest Hurdle for Python Devs Building on the Web — Reluctance to learn JavaScript and its pervasive low-quality online presence create significant development and code generation hurdles.

Open in AIssential →

Editorial summary, takeaway, and curation by AIssential. Original article published by The Computist Journal.