envzn
0.8 · beta · not released

“Readability” for a Systems Language?

Readability. Not a goal that most languages pursue. After having put code into production in over a dozen languages, and seeing the direction that some languages were taking (C++ has gotten quite complex compared with its past versions), I saw an opportunity to build a systems language that would have readability as a goal.

The problem with readability as a goal is that no one has ever created a standard for what this means. Some standards committees have considered it; ISO 25010 and ISO 5055 define maintainability and have stopped short of defining readability1. Python's motto is "readability counts"2, and Go considered it in its design3; they seem to be the exceptions. SonarQube, a code-analysis tool, even had to withdraw some guidelines about the ratio of comments to code lines, worried that future developers would add garbage comments just to “game the ratio” to satisfy their tool4.

Every experienced developer knows what “bad” code looks like: an alphabet soup of abbreviations, unexplained magic numbers, cryptic, unhelpful, or misleading names of elements, a lack of meaningful comments, “dense” and “packed” code accomplishing multiple tasks on one line, and sigils used often instead of their longer equivalents. Some languages are more susceptible to this than others - Perl is a great language but the competition among developers to accomplish in one line what a paragraph of lines would do was insane. Some lint programs guide developers to avoid these, but there’s no language that refuses unreadable code5.

So, I started with a simple and straightforward definition: readability means that a junior software engineer should be able to cold-read the code and adjacent comments, and understand what the code is doing.

This “simple” definition is much harder to measure than one would guess. Starting with the “junior software engineer” terminology; it’s a vague label implying “not much” experience in the field, and further, the “comprehension” expectation that this less-experienced software person could pick up code they’ve never seen before and understand it sounds a bit crazy.

However, in order to set readability as a goal, it needs to be measured. After many iterations, I’ve arrived at this for a readability rubric:

  • Names of elements (e.g. classes, variables, methods/functions) must be meaningful and inform the reader, but not necessarily use long names; a misleading name is worse than a cryptic one6. Common abbreviations and conventions are not just ok, they’re expected. For example, counting loops that use ‘i’ or ‘j’ are ok, and templates that refer to ’T’ as a generic type are ok.7
  • No unexplained magic numbers and literals, i.e. values that carry a hidden meaning8. The obvious exceptions in most languages are 0, 1, -1, length-1, count+1, and the empty String.
  • Each line of code should do or accomplish one task9. An assignment hidden inside an expression is doing more than one task.
  • Nested, tangled, or dense logic needs explanation. Functions should be short and shallow if possible10. Where complexity is required, comments are too.
  • For comments, quality matters most whereas quantity is a goldilocks problem - too much or too little could be symptoms of an issue11. Comments may be useful near public declarations of an element; include “why” notes beside any section where the reasoning is hard to follow. Based on public research and open source code, the average comment to code ratio is about 1:412. I recommend a window from 1:3 to 1:513.
  • Finally, each language must be judged by its own style guide; language nuances should not count against it. For example, the ‘?:’ operator in Kotlin is a recommended form and a valid choice for the author14.

While the above rubric is helpful, I needed to be able to score my code to improve it. The problem I then encountered was how to create a positive score when everything is done well. I found it much easier to generate a score based on the negative, when the presence of these “bad things” exists. Even so, it was not enough, so I began to think about how the junior software engineer would respond to poorly written code, which led me to my next idea. I decided to use a readability score based on the reader’s response and actions while reading, with the understanding that it’s very subjective15:

  1. Readable and understandable: Reads straight through with nothing to ask.
  2. Partially understandable: Pauses and resolves each pause on the spot.
  3. Difficult to read and understand: Has to stop and walk the code in their favorite IDE or on paper.
  4. Nearly unreadable: Unable to follow it without an outside spec.

The scoring for readability doesn’t judge readability directly. It looks for specific problems in the code based on the above bullet points to generate a grade16.

As part of this exercise, my first iterations were too biased toward Envzn, giving it scores above what it deserved. Envzn did too well. As readable as I think it is, I felt that these early scores were too generous. I asked AI to critique it to seek out the biases to make the scoring more balanced. It found three specific bias points:

  1. Envzn’s forced constructs were exempt
  2. The size rule was applied to loose code
  3. Envzn samples had been seen while the rubric was built.

Once these were fixed, our Envzn code landed in the middle of the pack, with specific, fixable problems: lines doing two jobs and names too short to say what they hold. After each adjustment, I asked AI for another round of critiques. After many revisions, I shaped the current readability rubric into what it is now. While Envzn isn't going to win any awards for readability, the scoring provided a clear work-list of possible improvements.

Even with this rubric, scoring a language remains difficult. Code samples vary greatly across languages and developers, so the goal here is not precision or accuracy. Instead, it is to create rough tiers of separation—based on limited samples—that shows how well a language encourages developers to write readable code, and whether they actually do so in publicly available projects.

Envzn's guiding idea is to move the hard parts into the compiler and the library so the code a developer writes is readable. This rubric highlights where that hasn't happened yet: every construct the language forces on an author, and every habit in our own library that makes a reader stop. A truly readable language is one where the most readable approach is also the easiest. Envzn isn't there yet, but I now have a list of exactly where it falls short, and a clear way to track our progress.

Disclaimer: These are judgements grounded in research where research exists, and stated as choices where it doesn’t17. The methodology is open for inspection and improvement. If you are a researcher in this field, please reach out.

End Notes and References

  1. ISO/IEC 25010 (systems and software quality models) names maintain-ability and analyze-ability as qualities but sets no thresholds for them. ISO/IEC 5055:2021 (CISQ) counts structural weaknesses mapped to CWE entries, which measures defects, not readability. Google's "readability" is an internal review certification, not a published metric: Winters, Manshreck and Wright, Software Engineering at Google (O’Reilly, 2020). ↩
  2. Tim Peters, "The Zen of Python," PEP 20 (2004): "Readability counts." https://peps.python.org/pep-0020/ ↩
  3. Rob Pike, "Go at Google: Language Design in the Service of Software Engineering," SPLASH 2012 keynote: “Go was therefore designed with clarity and tooling in mind, and has a clean syntax," and "syntax determines the readability and hence clarity of the language." https://go.dev/talks/2012/splash.article. Robert Griesemer, "The Evolution of Go," GopherCon 2015 keynote: "Simplicity, safety, and readability are paramount." https://go.dev/talks/2015/gophercon-goevolution.slide ↩
  4. SonarQube deprecated its 25% comment-density rule (SONAR-16051), calling the ratio "very artificial" and an invitation to "fake/useless comments." The one industrial floor still in use, the automotive HIS source-code metric COMF, asks for at least 0.2 comments per statement and states no evidence for it. ↩
  5. Go comes nearest: an unused import or an unused local variable is a compile-time error (Pike 2012, note 3). Those rules catch dead code, not hard-to-read code. ↩
  6. Eran Avidan and Dror G. Feitelson, "Effects of Variable Names on Comprehension: An Empirical Study," ICPC 2017. Misleading names did worse than meaningless ones. The study was small: nine professional developers. ↩
  7. Full words beat single letters and opaque abbreviations: developers found defects about 19% faster (Johannes Hofmeister, Janet Siegmund and Daniel V. Holt, "Shorter Identifier Names Take Longer to Comprehend," SANER 2017; 72 professional C# developers). Well-known abbreviations, however, were often no worse than full words (Dawn Lawrie, Christopher Morrell, Henry Feild and David Binkley, "Effective Identifier Names for Comprehension and Memory," ISSE 2007; Giuseppe Scanniello et al., TOSEM 2017). Conventional single letters such as i carry meaning by convention (Gal Beniamini, Sarah Gingichashvili, Alon Klein Orbach and Dror G. Feitelson, "Meaningful Identifier Names: The Case of Single-Letter Variables," ICPC 2017). ↩
  8. No controlled experiment comparing magic numbers with named constants was found. The only empirical work is a perception study (Nicolas Anquetil et al., "What Do Developers Consider Magic Literals? A Smalltalk Perspective"). The closest measured effect is the "atom of confusion" for a literal in an unexpected encoding, φ = 0.63 (Gopstein et al., note 9). This rule is convention, not evidence. ↩
  9. Dan Gopstein et al., "Understanding Misunderstandings in Source Code," FSE 2017 (C, 73 participants), measured small patterns that cause misreading. An assignment used as a value had effect size φ = 0.52, logic used as control flow 0.48, and the conditional operator 0.36. Ten of fourteen such atoms held in Java (Chris Langhout and Maurício Aniche, ICPC 2021). ↩
  10. Java methods under about 24 lines were less prone to maintenance work (Shaiful Chowdhury, Gias Uddin and Reid Holmes, "An Empirical Study on Maintainable Method Size in Java," MSR 2022, about 785,000 methods; the outcome measured is maintenance, not readability). Google's C++ style guide treats 40 lines as a prompt to split, not a limit (https://google.github.io/styleguide/cppguide.html#Write_Short_Functions). The three-level nesting limit comes from the Linux kernel coding style (https://www.kernel.org/doc/html/latest/process/coding-style.html). In an experiment with 220 professionals, nested ifs were no harder than one compound condition, though flat code was slightly easier than deep nesting (Shulamyt Ajami, Yonatan Woodbridge and Dror G. Feitelson, "Syntax, Predicates, Idioms — What Really Affects Code Complexity?", EMSE 2019). ↩
  11. Comments help comprehension in controlled experiments (S. N. Woodfield, H. E. Dunsmore and V. Y. Shen, "The Effect of Modularization and Comments on Program Comprehension," ICSE 1981; Ted Tenny, "Program Readability: Procedures Versus Comments," IEEE TSE 14(9), 1988). What matters is their quality and whether they still match the code (Daniela Steidl, Benjamin Hummel and Elmar Juergens, "Quality Analysis of Source Code Comments," ICPC 2013; Pooja Rani et al., "A Decade of Code Comment Quality Assessment," JSS 195, 2023, a review of 47 studies). Comments that drift from the code are a common failure (Fengcai Wen, Csaba Nagy, Gabriele Bavota and Michele Lanza, "A Large-Scale Empirical Study on Code-Comment Inconsistencies," ICPC 2019). ↩
  12. Across 5,229 open-source projects, about 19% of lines are comments, which is about 0.23 comment lines per line of code, roughly 1:4. Oliver Arafat and Dirk Riehle, "The Commenting Practice of Open Source," OOPSLA Onward! 2009 companion; and "The Comment Density of Open Source Software Code," ICSE 2009 (New Ideas and Emerging Results). ↩
  13. No study supports any target ratio. The 1:5 floor matches the open-source average (note 12) and the HIS floor of 0.2 (note 4), which counts per statement rather than per line. The 1:3 ceiling is my choice. Above it, more comments earn no credit, and a much higher ratio is a signal to check for narration, not a fault in itself. ↩
  14. Kotlin's own idioms page lists the elvis operator as the idiomatic "if-not-null-else" shorthand, including ?: throw and early returns. https://kotlinlang.org/docs/idioms.html ↩
  15. Human readability ratings are themselves noisy: in one study, up to a third of a rater's judgements contradicted that same rater's others (Antonio Vitale, Emanuela Guglielmi, Rocco Oliveto and Simone Scalabrino, arXiv 2503.07870, a preprint). ↩
  16. This is deliberate. Readability models trained on human ratings predict those ratings but not measured comprehension (Raymond P. L. Buse and Westley R. Weimer, "Learning a Metric for Code Readability," IEEE TSE 36(4), 2010; Simone Scalabrino et al., "Automatically Assessing Code Understandability: How Far Are We?", ASE 2017, where no metric captured understandability). Language models agree poorly with human readability ratings: weakly in Java (r = 0.25), near zero in Python (CoReEval, Ouédraogo et al., arXiv 2510.16579, a preprint). So the AI is never asked whether code is readable. It lists defined problems, and a program turns the list into a grade. The best-validated single metric, Cognitive Complexity, predicts comprehension time and perceived difficulty but not correctness (Marvin Muñoz Barón, Marvin Wyrich and Stefan Wagner, "An Empirical Validation of Cognitive Complexity as a Measure of Source Code Understandability," ESEM 2020). ↩
  17. Each rule in the full standard is labelled by where it comes from: evidence (a cited study), convention (a published style guide or industry floor), or a choice of ours, with the reason. For a survey of how code-comprehension experiments are designed, and why they are hard to do well, see Marvin Wyrich, Justus Bogner and Stefan Wagner, "40 Years of Designing Code Comprehension Experiments," ACM Computing Surveys 56(4), 2023. ↩