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.
@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 http://akkartik.name/post/wart-layers and http://akkartik.name/post/literate-programming 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.
@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
@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.
@Sandra contract + code meaning something like gherkin?
@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:
@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.
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