3 ms·
> Mr. Klabnik goes in depth into the argument that literate programming has to be tangled and weaved into a different order, in order to be considered "true" li
by jmillikin 16y ago
> Mr. Klabnik goes in depth into the argument that literate programming has to be tangled and weaved into a different order, in order to be considered "true" literate programming.
> Respectfully, I have to disagree.
If you're not re-ordering the code, there's no difference between a "literate program" and simple comments.
And I find code-reordering useful even in modern languages; most impose some structure like:
1. module-level documentation
2. exports
3. imports / includes
4. implementation (functions, procedures, etc)
4.1 return type (static languages only)
4.2 function/procedure documentation
4.3 code
With literate programming, you can add supporting text (like export entries, module imports, or documentation) wherever would make the most sense for a human reader, not to the compiler.
> At any point where you're tempted to pull out a block of code and interpolate it later, just make it a function with a descriptive name, and hey presto.
What if you've got a few dozen local variables? Do you want to pass them all as parameters, for every single logical block in your algorithm?
What sort of names do you give your extracted procedures? Literate programs can have block names like "Check for common post-traversal error conditions", which in a procedure name would likely be abbreviated to "traversed_errcheck()".
- jules 16y agoIt seems that folding code to a natural language summary is what you really want.
- jmillikin 16y agoNot at all; I want to be able to print stuff like this in the generated documentation: ---------------------------------------------- 3.2 HTTPS driver The HTTPS driver is currently implemented using either GNU TLS or OpenSSL: == driver includes #include <gnutls.h> #include <openssl.h> == driver list , {"HTTPS (GNU TLS)", driver_https_gnutls} , {"HTTPS (Open SSL)", driver_https_openssl} == drivers.c static void driver_https_gnutls(DriverState *s) { ||common driver local storage|| gnutls_init(); gnutls_ctx_init(&ctx); check_extra_algos = "FOO:BAR"; some_feature_flag = 1; // etc } static void driver_https_openssl(DriverState *s) { ||common driver local storage|| openssl_init(); check_extra_algos = "BAZ"; some_feature_flag = 0; // etc } ----------------------------------------------
- jules 16y agoI meant instead of pulling out a block of code and interpolating it later. For example instead of: <set up> <do stuff> <tear down> And then describing them in the rest of the document, a better solution to me seems to be able to click on e.g. the <do stuff> part to expand it. This allows the reader to see the high level structure and drill down to the stuff he's interested in instead of spreading the code all over the place with references.
- steveklabnik 16y agoThat might be an 80% solution, but it still means that you're tying your presentation to the way that the computer needs to have things ordered. What if all of the parts need explained, but I really want to explain the <do stuff> before the <set up> and <tear down>?
- RodgerTheGreat 16y agoWhat if you've got a few dozen local variables? Do you want to pass them all as parameters, for every single logical block in your algorithm? I'm not disagreeing with you, but it's interesting to note that in a stack-oriented language like Forth, PostScript or Factor this isn't a problem.
- munificent 16y ago> What if you've got a few dozen local variables? In that case, I would consider that I have a larger problem than merely one of documentation.