Follow

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 👌👌👌

@milofultz I agree (and I am hyped for someone finally getting the double-entry thing) but one thing about literate programming:
It's fun! It's so cute that it works and that people make programs this way. It's like, I don't know, adorable and it's for its own sake as dumb as it is. Like having flower stationary ♥

@Sandra I do dig the output! I was just looking at @paul 's Voc PDF and it is like the best manual ever for grokking a new thing.

I don't know the scope of how the tanglers and WEB utils really work, so I may be strawman-ing this whole thing, but I'd be worried about the changes becoming very daunting in terms of maintenance. That being said, I do love TDD and that's a whole lot of that, so ¯\_(ツ)_/¯. Maybe I am doomed to try this after all, as this is what usually happens

@milofultz The one double entry thing I like the least is type annotation because it's so limited compared to other forms of double entry coding.

@Sandra What other types of double-entry coding do you mean? I'm only really used to TDD/BDD type stuff

I really like type annotation in terms of integration with an IDE or compiler, as it's FAST, but I usually just make that a test in my suite so it's easy to see what I need to revise.

@milofultz Spec + code is one, contract + code another. Generally TDD feels like the most human & the most flexible.

Type annotation is one. I hate it. I hate typing foo(int bar, struct baz)

@milofultz @Sandra FWIW, I find Voc to be my least successful literate program. It was my first attempt, and ended up with a pretty document full of spaghetti code.

I think Kuf and Btprnt are better examples because for the most part I wrote the words first before the code:

https://pbat.ch/wiki/kuf/
https://pbat.ch/loom/kuf/

https://pbat.ch/wiki/btprnt/
https://pbat.ch/loom/btprnt/

@paul @Sandra so it's safe to say that a good project for literate programming is one where getting a solution out of your head onto paper first is ideal? Or at least that trying to do the writing and the coding in tandem may lead to the spaghetti you mentioned?

@milofultz @Sandra I'd say that's pretty fair. There was a time where'd I'd reach for LP by default for everything. Nowadays, I usually only consider it when I'm working on something and think "huh, this is actually complicated/confusing and could use some careful thought".

Writing and coding simultaneously if you know where both are headed. That doesn't happen often enough for me. Some of the DSP algorithms I implement for sndkit have a "rough draft" phase where I just code it out and make sure it works, then I go back and write it out. Admittedly, the literate programming in sndkit is often more comments++ and less LP.

Sign in to participate in the conversation
Merveilles

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.