3 ms·

The problem of literate programming, as with many of these systems, is that they presuppose a text file on disk with a parsing order. Fundamentally code is a gr

The problem of literate programming, as with many of these systems, is that they presuppose a text file on disk with a parsing order. Fundamentally code is a graph, we've just badly flattened it to a poor on disk format. If we could work, and annotate, at the graph level we'd see far more literate programming.

DominikD 10y ago
That's true, code is rarely linear. But the whole idea of encapsulation, separation of concerns and many, many other practices is to increase locality of a code. In that sense a well written and structured code has local, mostly linear systems that you can analyze in isolation to get insight into the larger system. With this in mind it doesn't matter that the overarching structure is much more complex. Translation unit you're analyzing is (or should) be mostly human-parsable in a linear fashion. What I found eye-opening in this article is that it challenged my concept of well structured code file. I was like "what?! this is blasphemy!" from the very beginning but at the end I was like "huh, I finally understand why sometimes #define's feel better in the center of a file than they feel at the top"[1]. It's rare for a blog entry to stir me like this. :) [1] amongst other things that came though my head
- akkartik 10y ago
  Thanks for the kind words!
MichaelGG 10y ago
This is why programming languages that support nesting really help in some scenarios. It's great to be able to write functions inside functions, with or without captured variables/bindings. (I know a tree isn't all graphs, but it works well for many scenarios.) When I start on a new program in F#, I usually just start with one main function and keep typing straight on down. When I want to re-organize it into a module, it's usually nearly as easy as writing "module" at the top. Without this, one is encouraged to either not abstract properly as the overhead and context for a new top-level function is too much, or you end up with free-floating functions that don't belong there and only have a single caller.

DominikD 10y ago

That's true, code is rarely linear. But the whole idea of encapsulation, separation of concerns and many, many other practices is to increase locality of a code. In that sense a well written and structured code has local, mostly linear systems that you can analyze in isolation to get insight into the larger system. With this in mind it doesn't matter that the overarching structure is much more complex. Translation unit you're analyzing is (or should) be mostly human-parsable in a linear fashion. What I found eye-opening in this article is that it challenged my concept of well structured code file. I was like "what?! this is blasphemy!" from the very beginning but at the end I was like "huh, I finally understand why sometimes #define's feel better in the center of a file than they feel at the top"[1]. It's rare for a blog entry to stir me like this. :) [1] amongst other things that came though my head

akkartik 10y ago
Thanks for the kind words!

MichaelGG 10y ago

This is why programming languages that support nesting really help in some scenarios. It's great to be able to write functions inside functions, with or without captured variables/bindings. (I know a tree isn't all graphs, but it works well for many scenarios.) When I start on a new program in F#, I usually just start with one main function and keep typing straight on down. When I want to re-organize it into a module, it's usually nearly as easy as writing "module" at the top. Without this, one is encouraged to either not abstract properly as the overhead and context for a new top-level function is too much, or you end up with free-floating functions that don't belong there and only have a single caller.