Literate programming is much more than just commenting code
Ok, that will be unpopular.<p>&quot;Literate programming&quot; is a non-invention by somebody (Knuth), who is very much revered by many programmers (many of whom never even actually read him), but who was — let&#x27;s admit it — just terrible at writing readable code. I&#x27;m very much not a fan of the &quot;Clean Code&quot; by Martin, but he had a very nice example of refactoring some of Knuth&#x27;s code to show you what I mean (although, it&#x27;s kind of evident that writing clearly wasn&#x27;t in Knuth&#x27;s DNA just by reading his famous books). Today, this is an attempt to solve a problem, which you created yourself by avoiding using tools that already exist to solve that problem. Then you invent all sorts of tooling and mental tricks to make solving this problem <i>your way</i> more comfortable. But if you would just use these <i>already existing</i> tools, there would be no need in making up a new name for what you do. It wouldn&#x27;t be some &quot;literate programming&quot;, it would be just <i>programming</i>, <i>the sane way</i>.<p>First off, what tools I&#x27;m talking about: well, that&#x27;s everything PL developers invented over the decades, and it obviously depends on which PL you are going to use. If this is some pseudo-assembly language like what Knuth uses in his TAOCP, then, well, there aren&#x27;t many such tools, so creating your own template-preprocessor (which is, in a sense, making a new PL with additional features on top of your pseudo-assembly) perhaps would be an okay-ish idea. But if you use something that people <i>actually use for programming</i>, then you surely have functions, some kind of advanced data structures, perhaps classes and inheritance, perhaps some templating features as well (like… traits?).<p>Going back to the example at hand (the code author &quot;simplifies&quot;): all that &quot;simplifying&quot; consists of a top-down description of what he&#x27;s going to do. Really, the code he ends up with (in &quot;transpiled&quot; form) isn&#x27;t that much harder to read and understand than his &quot;LP&quot; version of it. Inline some comments to explain what he explains in the &quot;LP&quot; version, and you and up with the same thing, but much more concise (so, faster to read — and easier to edit!). If it was a bit more complicated: you do the same thing that he did with his &quot;templating&quot;, but simply by doing what programmers actually do in such cases — extract complicated fragments of a function into smaller functions, and give them proper names. Maybe add some comments — yes, they are a part of your PL for a reason.<p>Moreover, the most complicated thing in his example isn&#x27;t <i>how</i> the algorithm is written down, but the very algorithm itself. It is ok as long as you never actually run this code, but if you actually use it in some useful program, where it can cause problems, a programmer coming across this thing would need to stop to wrap his head around what this is doing, if it&#x27;s actually all subsets and how fast the call stack may grow (as it so often turns out when you use recursion to write down &quot;an elegant&quot; solution). I mean, I&#x27;m only suggesting, but wouldn&#x27;t this be a little bit more straight-forward?<p><pre><code>    function subsets(elements) {
        results = []

        &#x2F;&#x2F; All subsets of a set of 5 elements are basically binary numbers 
        &#x2F;&#x2F; from 00000 to 11111, which is from 0 to 2⁵-1
        for (i in range(0, 2^(len(elements)) - 1) {
            results.add(get_subset_by_binary_number(elements, i)))
        }
        return results
    }

    &#x2F;&#x2F; Blah-blah
    &#x2F;&#x2F; Given [1, 2, 3, 4] and a number with binary representation 0101
    &#x2F;&#x2F; will return [2, 4]
    function get_subset_by_binary_number(set, number) { ... }

</code></pre>
This isn&#x27;t my main point, though. My main point is, that people write code for a reason. There can be number of reasons, but usually it fits into a range from &quot;doing some enerprisy-boilerplaity stuff I&#x27;ll need to redo over again next week&quot; and &quot;writing a book, which has code, because it&#x27;s about programming, and code describes programming better than english&quot;. In the first case it probably won&#x27;t need a lot of &quot;LP-kind of explanations&quot;, and where it needs to go over &quot;why the fuck did I do it like that&quot; a bit more extensively, you&#x27;ll just link Jira issue in a comment. In the second case it might look a bit moe like LP, but it&#x27;s just called &quot;writing a book&quot;.<p>In all of the cases in between you&#x27;ll add some amount of comments, always trying to minimize overall amount of stuff other people will have to read (and, well, you to write), which is expressing as much as you can with words you cannot avoid to write (i.e., code that actually does things, explaining them both to humans and to a computer) and minimizing what you can avoid (i.e. English). (Closer to &quot;a book&quot; on this spectrum it will also include some Jupyter Notebooks.)