5 ms·

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

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.

bigyikes 2y ago
“Story” mode is why I like to organize my code top-down, often with definitions appearing after their usages. 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.
- rav 2y ago
  Both programs and math proofs are allowed to be written in story mode where definitions can come after their usages. Unless you write in C. There's no story mode in C :-)
  - Bootvis 2y ago
    There is CWEB. Literate programming is the ultimate story mode.
    - NavinF 2y ago
      wtf is CWEB? I presume you're referring to something other than "China Internet Index Bull 2X ETF"?
      - gshubert17 2y ago
        See: http://literateprogramming.com/cweb_download.html http://literateprogramming.com/cweb_download.html
      - eru 2y ago
        The clue is in the next sentence. 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'.
  - kloop 2y ago
    If you forward declare things there are. The compiler really just cares about the shape and the symbol it has to call.
  - shermantanktop 2y ago
    But there’s a postmortem, in the core file. Maybe that’s just a photo of the crime scene.
  - bandie91 2y ago
    in C there is only epic mode :)
  - lynx23 2y ago
    Sure there is, what do you think header files are? Just use a prototype and defer the actual code to a lter point in the file, voila, story mode.
- threecheese 2y ago
  That’s so interesting. I find myself organizing code to have minimum-understandable units, which ends up following the narrowing project->folder->file… abstraction all the way down - the end product resembles more a taxonomy than a story. I love your metaphor though and I am going to try it right away.
  - lloeki 2y ago
    See https://en.wikipedia.org/wiki/Literate_programming https://en.wikipedia.org/wiki/Literate_programming
- Wowfunhappy 2y ago
  > “Story” mode is why I like to organize my code top-down, often with definitions appearing after their usages. Yes, it drives me nuts that e.g. Python makes you put the definitions before their use!
  - yashasolutions 2y ago
    well, it is like introducing the characters before they play a role
    - eru 2y ago
      Compare https://en.wikipedia.org/wiki/In_medias_res https://en.wikipedia.org/wiki/In_medias_res
      - saurik 2y ago
        Yeah: to me, it really depends on the story being told, and frankly even then it might depend a bit on the proclivities and interests of the person reading the story. 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 :/.
        eru 2y ago
        That's part of why Knuth came up with Literate Programming: he wanted to be able to present the reader of his code with a coherent order that makes sense to understand the project. 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) 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.

bigyikes 2y ago

“Story” mode is why I like to organize my code top-down, often with definitions appearing after their usages. 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.

rav 2y ago
Both programs and math proofs are allowed to be written in story mode where definitions can come after their usages. Unless you write in C. There's no story mode in C :-)
- Bootvis 2y ago
  There is CWEB. Literate programming is the ultimate story mode.
  - NavinF 2y ago
    wtf is CWEB? I presume you're referring to something other than "China Internet Index Bull 2X ETF"?
    - gshubert17 2y ago
      See: http://literateprogramming.com/cweb_download.html http://literateprogramming.com/cweb_download.html
    - eru 2y ago
      The clue is in the next sentence. 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'.
- kloop 2y ago
  If you forward declare things there are. The compiler really just cares about the shape and the symbol it has to call.
- shermantanktop 2y ago
  But there’s a postmortem, in the core file. Maybe that’s just a photo of the crime scene.
- bandie91 2y ago
  in C there is only epic mode :)
- lynx23 2y ago
  Sure there is, what do you think header files are? Just use a prototype and defer the actual code to a lter point in the file, voila, story mode.
threecheese 2y ago
That’s so interesting. I find myself organizing code to have minimum-understandable units, which ends up following the narrowing project->folder->file… abstraction all the way down - the end product resembles more a taxonomy than a story. I love your metaphor though and I am going to try it right away.
- lloeki 2y ago
  See https://en.wikipedia.org/wiki/Literate_programming https://en.wikipedia.org/wiki/Literate_programming
Wowfunhappy 2y ago
> “Story” mode is why I like to organize my code top-down, often with definitions appearing after their usages. Yes, it drives me nuts that e.g. Python makes you put the definitions before their use!
- yashasolutions 2y ago
  well, it is like introducing the characters before they play a role
  - eru 2y ago
    Compare https://en.wikipedia.org/wiki/In_medias_res https://en.wikipedia.org/wiki/In_medias_res
    - saurik 2y ago
      Yeah: to me, it really depends on the story being told, and frankly even then it might depend a bit on the proclivities and interests of the person reading the story. 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 :/.
      - eru 2y ago
        That's part of why Knuth came up with Literate Programming: he wanted to be able to present the reader of his code with a coherent order that makes sense to understand the project. 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) 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.