[HN Gopher] Show HN: Wordle in Python using literate programming
___________________________________________________________________
Show HN: Wordle in Python using literate programming
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...
Author : FrenchyJiby
Score : 59 points
Date : 2022-05-08 17:53 UTC (5 hours ago)
(HTM) web link (jiby.tech)
(TXT) w3m dump (jiby.tech)
| JasonFruit wrote:
| 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 wrote:
| 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 wrote:
| 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
| tunesmith wrote:
| 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 wrote:
| 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 wrote:
| 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.
| jonahx wrote:
| 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.
___________________________________________________________________
(page generated 2022-05-08 23:00 UTC)