Digging more into literate programming to see what it's all about, and I still don't quite understand.

It seems like it has some of the benefit of something like TDD (double-entry bookkeeping of code and expected results), but without the explicit tests, which seems to be the glue keeping both sides in sync.

It also seems like it would run into the common comment complaint, which is that a bad comment is worse than no comment. But this time with gobs and gobs of comments.


I get it in theory, but the real-world maintenance cost seems to really counteract the perceived benefit, without the green light to know that your two sides match (a la TDD).

I'm probably wrong and I know that @akkartik and @paul have opinions on this

@milofultz @akkartik Not everything benefits from a LP style. Most of what we would call "modern-day software engineering" wouldn't work too well using it IMO.

@paul What kinds of projects would benefit? Or maybe a better a question, what axes would most greatly affect the benefit it may have (e.g. complexity, scope, implementation space, idk)?

@milofultz Complex programs/algorithms that aren't changing much and usually are maintained by one brain or so. The types of programs where the actual "coding" is incidental, and the thought-process leading up to is more valuable.

@milofultz @paul I do LP with tests, so they feel complementary.

The problem LP solves is giving a single obvious place for any comment where readers are likely to find it. Turn a program into a room of requirement. Comments only go out of date if they're not in the obvious place. (Even outside LP, I rarely encounter stale comments.)

Nobody uses LP because we don't prioritize documentation over familiar tooling. Most people would rather make their build more baroque for shittier reasons 🙂

@milofultz @paul There's also the problem that what I consider the most useful properties of LP isn't commonly agreed upon. So I'm just a man yelling at a cloud.

@milofultz @paul Well, you've probably already seen akkartik.name/post/wart-layers and akkartik.name/post/literate-pr since you tagged me.

The #1 task of programming is convincing others that it works. Trust but verify, etc. The order of sentences is more important than following style guides, typography, etc. Introduce more important ideas before less, define terms before using them. Start with the bones of a program before describing frills.

@milofultz @paul Most LP tooling exists to eliminate constraints on ordering imposed by other tools. If you start out with more enlightened tools (e.g. Haskell or Clojure) you need less LP tooling. Though there are still constraints no conventional tools remove, as my layers idea shows.

@akkartik @paul love reading your writing, it's always so clear what you're getting at 👌👌👌

Sign in to participate in the conversation

Revel in the marvels of the universe. We are a collective of forward-thinking individuals who strive to better ourselves and our surroundings through constant creation. We express ourselves through music, art, games, and writing. We also put great value in play. A warm welcome to any like-minded people who feel these ideals resonate with them.