Why do or dont you use literate programming techniques?

if I can’t even keep my docstrings up to date, what hope do I have in keeping additional prose correct? really good literate programs also take exceptional care about the “story” and order inherent in the code. I have no desire to add that additional constraint on either initial dev or refactoring. that is, my perception is that there is substantial cost to using literate programming with unproven roi.

so that’s my don’t :)

I mostly agree with Alex. I've tried it several times and I've not found it to help with maintenance at all. On one project, I found it helped with the initial design/build: the requirements were very sparse, so I write it all out in prose and used Marginalia to generate HTML which I shared with the business team. We went back and forth over the text several times, and I slowly started converting the prose to code, but then found the prose/comments inside the code just made the code hard to read in my editor (the generated HTML was fine).

Good, easy-to-read code should not need/have comments littered through it, in my opinion.

But literate programming really focuses on the text, with the code almost as a secondary concern, and that seems backwards to me.

@alexmiller Thanks for sharing.

That project has ended up with a fair bit of prose still, in "section" comments between groups of functions and in some (overly) large docstrings. And at this point, the code is drifting away from the prose and docstrings -- which makes it misleading and an obstacle to future maintenance. So simply removing the text would help at this point.

I’d be more interested in tools that help explain the code that exists than write static text that tries to explain it

☝️:skin-tone-2: Yes, this!

I love the idea of literate programming and someone sitting down with a pipe in their library to consume the great works of code…. that just doesn’t match the reality I live in :)

lol

is there a literate programming framework in Clojure that allows you to instrument fns separately, perhaps from another ns, which live in a registry, similar to spec?

So I wouldn't have to couple my doc with my code?

@john That sounds like an even bigger recipe for code and docs getting out of sync!

with the idea that they'd be "consumed" through some viewer

@seancorfield good point. But perhaps chasing that goal is too hard. Perhaps the leverage of having a manageable doc-base would be more beneficial than having them up-to-the-minute current with the code... Not sure.

And that assumes the docs could be consumed by various tools

or views

I've never worked anywhere that seems able to keep their documentation up-to-date with their code, making the documentation anything from useless to only mildly helpful.

aye

Only very high level documentation ever seems to remain accurate.

Part of the problem is that its hard to define the goal.

The reward for doing the thing were trying to do is somewhat more clear. Its not clear what there is to gain from helping people understand it. Or what would help them understand it.

you don't know what they don't know they don't know 😂

My intuition is to agree with @seancorfield @alexmiller and @john on that its hard to justify the effort. To @alexmiller’s point, and one which i have given a little thought, i think there might be an opportunity to design in such a way that your system explains itself both at the functionality level but that also tells a narrative. For example, the code is very open ended, you can pass any number of options… but a narrative would tell me which options people usually pass and show me what the normal output_ looked like. I think in order to do this, the system would need side effects to be isolated. I suspect there is nothing novel here 🙂