Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Literate programming is much more than just commenting code

justinmeiners.github.io

Post reply on HN
Print view View original

71–80 of 112 posts

Re: Literate programming is much more than just commenting code

#71

Post by vim-guru »

I've written a fair share of literate code.

It works well for personal stuff where you would like to leave some bits of information for yourself (typically, configuration files).

It works well for small libraries where good documentation is important.

It works well for visualisation-work, where you may combine multiple languages and data-formats without writing API's for each.

In larger scale apps though and with collaboration; you run into problems with tooling on multiple levels. I am working on tackling scale, but collaboration is tricky. Mostly because you need structure to collaborate and then you will likely end up with an outline that's pretty close to a directory-tree and then you've lost one of the good bits of literate code in my opinion.

Re: Literate programming is much more than just commenting code

#73

Post by fjfaase »

atweiden wrote: post #27

I’d like to see a literate programming version of GitHub where the community standardizes around an eminently-readable Markdown-like syntax. srcweave [1] looks like a great start. [1]: https://github.com/justinmeiners/srcweave

I have started working on a program that can parse Markdown files with fragments of C code and weave those fragments into a C program that can be compiled. For an example input, see https://github.com/FransFaase/RawParser#documentation

Re: Literate programming is much more than just commenting code

#74

Post by krageon »

taeric wrote: post #63
copperx wrote: post #2

It would be great if IDEs supported literate programming; the tangle/weave commands, simple as they are, create many possible points for navigation. An IDE would be ideal to go back and forth from the prose to the code.

You will be shocked to know that emacs and org-mode can do exactly this. You can tangle source, and go from the tangled source back to the section that generated that source. If you are wanting to just do cweb, then the debugging symbols already let you step through the source line by line without having to look at the tangled source.

> You will be shocked to know that emacs and org-mode can do exactly this. You can tangle source, and go from the tangled source back to the section that generated that source.

If you actually use noweb and desire autocompletion or type reminders (or really anything an IDE does), then functionally it cannot. Literate programming (and noweb) is great for configs, but as set up it simply doesn't work right for real programming.

Re: Literate programming is much more than just commenting code

#75

Post by medstrom »

kwhitefoot wrote: post #70
mci wrote: post #65

IMHO, attempts to show literate programming on screen are doomed to meet with mediocre success. DEK invented literate programming with printed books in mind. I dare say that the only successful literate programs are books printed on paper. First, in a printed book, it is easier to find a previous page and compare a fragment on it with the current fragment. Second, a printed book has no links tempting you with the wor…

> in a printed book, it is easier to find a previous page and compare a fragment on it with the current fragment. This is why I like plain text for everything (or Emacs Org Mode) because then I can have multiple frames showing different parts of the same buffer in Emacs.

You can also create several browser tabs visiting the same page. Of course, no one thinks to do that.

Re: Literate programming is much more than just commenting code

#76

Post by sritchie »

Literate programming is going to feel far more powerful when we expand the definition to include:

- Smalltalk-ish things like writing suites of custom viewers for various types, - demos and examples in-line inside of a library - multiple stories about the same piece of code, but all with the ability to IMPORT the story as a library

I've been writing sicmutils[0] as a "literate library"; see the automatic differentiation implementation as an example[1].

A talk I gave yesterday at ELS[2] demos a much more powerful host that uses Nextjournal's Clerk[3] to power physics animations, TeX rendering etc, but all derived from a piece of Clojure source that you can pull in as a library, ignoring all of these presentation effects.

Code should perform itself, and it would be great if when people thought "LP" they imagined the full range of media through which that performance could happen.

[0] sicmutils: https://github.com/sicmutils/sicmutils

[1] autodiff namespace: https://github.com/sicmutils/sicmutils/blob/main/src/sicmuti...

[2] Talk code: https://github.com/sritchie/programming-2022

[3] Clerk: https://github.com/nextjournal/clerk

Re: Literate programming is much more than just commenting code

#77

Post by majewsky »

JasonFruit wrote: post #34
ggm wrote: post #30

I have always felt a literate program is probably for many of us, a future deliverable on the hack we've implemented up front. Very very few people can start from the abstraction and get TO a literate outcome without a lot of false steps along the way. Or, as an alternative, the LOC of a literate program has to include the 100x cost of exploring how to carve it out of the block of mud we start from, including making…

The cool thing is that if it's valuable, you can leave the iteration artifacts in the literate document, not as commented-out blocks like we often see, but as a part of the explanation of how we arrived at the final version of our solution. Not all code that's in the document has to end up in the compiled/executed files.

I had an instance of this where I built up a rather contrived data structure over time and ended up putting what is basically a blog post into the repo to explain the history of that data structure: https://github.com/majewsky/rust-jmdict/blob/main/CONTRIBUTI...

Re: Literate programming is much more than just commenting code

#78

Post by floodyberry- »

mci wrote: post #65

IMHO, attempts to show literate programming on screen are doomed to meet with mediocre success. DEK invented literate programming with printed books in mind. I dare say that the only successful literate programs are books printed on paper. First, in a printed book, it is easier to find a previous page and compare a fragment on it with the current fragment. Second, a printed book has no links tempting you with the wor…

I always feel like I'm missing something about literate programming because every example is "godawful". Transitioning between text and context-less code fragments littered with markup is incredibly jarring, and instead of something "written for humans", you now have something that is neither text _or_ code that you have to piece together and hold in your head as you go.

Re: Literate programming is much more than just commenting code

#79

Post by derangedHorse »

Maybe I'm missing something, but I didn't find his way of programming to be all that more useful than just having well written code. The small code snippets are labeled and shown where they are referenced but this seems to mimic the functionality of functions which, when using an IDE like Visual Studio, can have where it's referenced identified through tooling.

Re: Literate programming is much more than just commenting code

#80

Post by zozbot234 »

derangedHorse wrote: post #79

Maybe I'm missing something, but I didn't find his way of programming to be all that more useful than just having well written code. The small code snippets are labeled and shown where they are referenced but this seems to mimic the functionality of functions which, when using an IDE like Visual Studio, can have where it's referenced identified through tooling.

The original literate programming was designed for early programming languages like Pascal, where support for forward references would've gotten in the way of efficient parsing and compiling. As you point out, it's less useful nowadays and it's been largely superseded by "lightweight" literate systems where formatted and structured documentation is programmatically extracted from the code rather than the converse.
Post reply on HN