That’s an excellent point.
I’ve realized that I sometimes read code in more of a “story” mode, where I’m just looking for the gist of what’s happening and what it is “about” rather than the nuts and bolts of how it actually works.
I’ve realized that I sometimes read code in more of a “story” mode, where I’m just looking for the gist of what’s happening and what it is “about” rather than the nuts and bolts of how it actually works.
It makes the code read more like a story from top to bottom.
Some like to organize their code such that any term always appears before it is used. Like a math proof or something. I find this somewhat pleasing but unhelpful for understanding the “story” you mention.
Maybe that’s just a photo of the crime scene.
If you look for cweb by itself, you might get weird results, because there are only so many four letter acronyms / words. Look for 'literate programming cweb' or just 'literate programming'.
Yes, it drives me nuts that e.g. Python makes you put the definitions before their use!
The one thing I'd say almost never works for reading code, though, is the thing people seem to insist is best practice: scattering everything into a hundred separate files with no clear order at all!
Trying to understand that code is like sitting down to an encyclopedia and then being asked to somehow use it to answer to the ultimate question of life, the universe, and everything.
The worst is when you grep the code for "main" in an attempt to at least come to your own idea of order, and it turns out that a bunch of files have their own main functions for various unit tests in files the build system just happens to ignore :/.
Given the strict formal requirements on order of languages like Pascal, Knuth had to come up with a clever preprocessing scheme to satisfy both the reader and the compiler. (See his tool, https://en.wikipedia.org/wiki/Web_(programming_system) )
Modern languages are a bit more flexible, but can still benefit from some re-ordering.
> The worst is when you grep the code for "main" in an attempt to at least come to your own idea of order, and it turns out that a bunch of files have their own main functions for various unit tests in files the build system just happens to ignore :/.
I used to use tools like grep a lot, but I found that my productivity really improved a lot when I set up an environment that supports 'jump to definition' and 'jump to references' etc.
> Python makes you put the definitions before their use!