3 ms·
In my experience, code bases are best structured for navigability, I.e., so that you can find what you’re looking for. Literate programming is about narrative,
by wduquette 2y ago
In my experience, code bases are best structured for navigability, I.e., so that you can find what you’re looking for. Literate programming is about narrative, telling the story of the code in a clear way so that you can build your mental model. These two needs are frequently orthogonal.
- josh-sematic 2y agoFirm agree. To me the best way to build a mental model of some code is to be able to quickly answer the questions that arise in my mind as I read it. The order in which these questions arise differ for each reader, and indeed for each intention that you approach the code with. There is therefore no one “perfect linear order” the code could be presented in and the best you can do is make it easy for the reader to construct their own reading order by being able to easily navigate around.
- WillAdams 2y agoI find that Literate Programming and being able to read through a nicely typeset, hyperlinked document with an index and ToC and marginal callouts of variable and routine names helps quite a bit in this.
- lou1306 2y agoBut that is the point of the article. Literate programming was built on the premise "what if you could have _one_ document that you could either typeset as an article/report _or_ compile as a program?", but then most implementations only cater to the second part of the equation and essentially default to "comments on steroids". Being able to expose pieces of code in a non-linear way would be a basic necessity, so that you can put the "interesting stuff" front and center and only focus on the minutiae (e.g., the #includes) later in the exposition.