It’s definitely an impressive piece of software and I realize that his thesis is much more than just “comments” to the code.

My objection was to the implied claim that a 1000 line program is easy to understand and work with, easier than a much longer program. I don’t think that’s true if the 1000 line program is written in an incredibly terse style where a lot of contextual information has been deliberately eliminated.

For example, in this post Aaron comes up with a bit of APL that’s a direct transliteration of “ Description #5: Increment the n field of the parent for nodes whose parent is of type 2 and kind 3 for each node by 1.”

My claim is that an experienced APL and compiler programmer could figure out what the APL is doing at the level of “description 5”.

But I think he/she would struggle to recognize the problem statement at the top “Pass Overview: Count the Rank of Indexing Expressions” because a lot of contextual information has been lost in the transliteration to APL. That information could have been included in the code in the form of comments or by assigning a helpful name to this snippet.

Aaron didn’t do that by design, and he didn’t need to because he’s been working on this for years. It’s all in his head and now in his thesis. But if you’re not Aaron you have to read the thesis to learn the missing contextual information.

Dyalog’s dfns library is including the contextual information inline in the form of comments and local utility functions. I prefer that to having to cross-reference some other piece of documentation.