Wordle in Python using literate programming

[FrenchyJiby]

https://jiby.tech/project/literate_wordle/wordle.html

Hey HN!

I wanted to demo TDD with Python, as well as showcase some BDD practices I've been blogging about recently[1]. So I used literate programming to implement Wordle, and rendered the narrative into this "Show HN" webpage.

I'm certainly no Knuth, but I'm pretty proud of the result. Proud enough to chance myself to a HN post, and risk HN's mockery and ire: my first "Show HN".

I hope this crowd will enjoy this annotated walkthrough of Wordle implementation in Python. Codebase available on Github[2].

Relevant for folks here (though not covered in the main narrative) is how the Gherkin files are listed as Requirements[3] via Sphinxdocs extensions[4]

[1]: https://jiby.tech/ [2]: https://github.com/OverkillGuy/literate-wordle [3]: https://jiby.tech/project/literate_wordle/_collections/gherk... [4]: https://github.com/OverkillGuy/literate-wordle/blob/6d51eb6d...

[jonahx]

As an example of literate programming, this is very well done, and the presentation is very pretty.

With that said, it is not the ideal way (for me) to explain code. There is too much too read, even with the TOC. What I want, instead, is distillation. I want the energy spent on meticulous comments to be redirected into simplification and reduction -- still with a few well-chosen comments for support.

For comparison, even with 0 explanation, I can understand this 57 line hyperscript wordle (a language have almost no experience with):

https://arhamjain.com/hyperwordle/

much more quickly than I could read through the literate version. I understand the goals of each are not exactly the same, but I think both are trying to "clearly and efficiently communicate what the program is doing."

Perhaps a presentation of the literate version where I could suppress all the exposition and dig into it only as needed would help.

[wodenokoto → jonahx]

I think the power of literate programming is not so much the ability to explain the code as it is to explain the problem and how it was solved.

In this case the problem is not “how to write wordle”, but “how to use test based development in Python, with wordle as an example”

With that said, I agree that it gets a little tedious to read at times.

[tunesmith]

I'm curious, while writing the commentary, did you feel conflicted about what perspective to write from? The evaluation order of code isn't linear, it's more like a directed acyclic graph (or at least a directed cyclic graph that eventually terminates), and so what you want to write for a certain area of code might change depending on how it is called.

[FrenchyJiby → tunesmith]

Hey, OP here.

Good question! Indeed, I tried initially to write this as a top-to-bottom thing that tangles in the "obvious" (sequential) way.

This proved limiting quickly because of my intention to run formatting/linting tools (secondary objective of "showcase modern Python" conflicted with the literate programming one). Successive code blocks for the same file were separated by a single line, but Python functions require 2 lines of separation to match PEP8 formatting.

Similarly, some of the TDD aspect of "define a stub function to get a red test" meant that to re-write the function later, I'd have to overwrite an "old" (in narrative timeline) codeblock, so I would need out-of-order tangling anyway.

I did consider if I really wanted to show the out-of-order tangling blocks, as it looked a little ... unclean? But eventually it felt like a good enough review/summary step of each feature, debriefing on the resulting code.

The real value of this out of order tangling was stuff like adding the @cache decorator way after initially definining the function itself, felt like a big win.

A few last-second edits (see the git history, it's fun...) of the code to fix bugs/warts made me re-visit some sections, and as I mention in sibling comment, I definitely had to reconciliate the tension "narrative-as-I-built-it" vs "proper-but-ex-post-facto".

[kwatsonafter]

I was just reading about Literate Programming. I'm excited to see a, "real" example here. I think that if you can kind of harness, "the power of language" programmatically you can get a lot closer to machines as amplifiers of human thought vs. manipulators of abstract symbols.

[JasonFruit]

This is a really nice example: toy enough that it's easy to understand and you don't get bogged down explaining the problem, but meaty enough that it shows some of the things you have to think about in real-world projects. I hope lots of people see this.

I have a mental hangup about literate programming that is like how I feel about practicing hard musical passages with a metronome: it works so well at getting me over the hump into competence that I fear overusing it and wearing out the mental effect. Do magic spells get used up over time?

[Jtsummers → JasonFruit]

There's a difference between LP (or TDD or ...) working to help you improve your programming and get over hurdles versus a metronome. A metronome is a practice aid, when you perform you will generally not use it (though in an ensemble, someone or some group is often playing the part of the metronome in establishing the beat). With LP and other techniques they are not practice aids (or not just practice aids) but performance approaches. Now, you may not use them all the time, you may not find them generally applicable, but that doesn't mean that you should skip it if it gets the job done.

In this case, the more you use it the more natural it will become for you. That means you'll be able to use it with greater fluidity and move in and out of the mode of literate programming (versus more traditional programming styles). Maybe you think, "I know what to write in code, let me just blurt it out." You do, you get it done. Then you reorganize and put it into a literate style because you like that presentation better, or you've reached a point where you need to clarify your thoughts before moving on ("I'm not sure what to do next, or is this really what I wanted? Let's examine it.").

[FrenchyJiby → Jtsummers]

Hey, OP here.

I'm a heavy proponent of "we play (at work/in prod) like we practice (in personal projects)", so that idea of TDD/LP as "peformance approach" is interesting. Thanks for that.

And on the tension between initially "after the fact" rationalization vs as-you-go LP, I tried to keep myself honest: The git repo has tags for each feature's initial completion[1]. One can indeed compare how the features were initially written vs how they ended up after the (heavy) editing passes. As you'll see, it's more than just more explicit text, there's a few bugs/warts that I cleaned up. Definitely felt this tension of "I can make it better" vs "I should keep the narrative intact".

[1]: https://github.com/OverkillGuy/literate-wordle/tags

[deostroll]

On a lighter note, I think someone I know might have resorted to this programming technique way back in my engineering college days...albeit without results (or shall I say "requirement marks for the exam question").

The program was to compute a factorial in C. It had to be written on the answer paper. The first few lines where the usual headers, then the main block. Inside the main block was a "novel" on how to accomplish the computation. (That was not even in comments).

Makes me smile thinking about this even today...