Clojurians Log v2

Should you feel inclined, the Clerk team would enjoy reading which felt the rough edges or difficult/unintuitive aspects of the system 😊

That was an amazing read! I think the choice of problem domain really lended itself well to this format, being familiar enough for readers to grasp without much explanation, but not so trivial as to make the visualizations and literate programming seem like incidental fluff. This will probably be my new go-to for demonstrating the power of data-oriented modelling that Clojure encourages :)

Just curious, to what extent did your process of developing the code naturally involve working alongside Clerk and making/using these viewers? Or was it more of an tool written after the fact to illustrate things? I've attempted to use Clerk 'in anger' a couple of times in the past, but for one reason or another it never quite stuck, something about the push to write code that flows in an expository fashion seems to be in tension with other pressures or habits.

A few bits of feedback, from the perspective of having taught Clojure to complete beginners: - Keyword syntax was never introduced explicitly, seeing colons for the first time in {:pieces #{} :row 8} might confuse some into thinking it's part of the map syntax. - The syntax of let can (surprisingly) be a tripping point for those unfamiliar with it – simply pointing out that it's binding new 'variables' for use in subsequent expressions could help things click faster (aha, like there's a silent = between words) - Similarly a few words about the ->> macro and #() shorthand the first time they were introduced would be great, even just a footnote linking to another reference like https://clojure.org/guides/weird_characters Of course it's unrealistic to fully explain every bit of clojure.core that's on display in the article, but I think that's about the bare minimum for a newcomer to be able to skim the code and get a high-level understanding of the ideas, even if they don't know the meanings of assoc etc.

yep, great feedback. I did find myself wondering whether I should extend it a bit more and make it an intro to Clojure the language too... it's not too far from it ... but wanted to finish something 🙂 .. If I do that, it'd almost become a mini-book

To your original question about Clerk: a good question... hmm... my goal since day one (before even starting to work on the problem) was to explain my attempt at it. So I used Clerk from the start, as a way to write and my thoughts as I went. It did become helpful eventually... seeing the boards does help to see the impact of implementing piece moves 🙂. The viewer for test failures was a very practical thing to do, not at all faked for the article.

All that said, I've spent many hours fighting/learning Clerk in order to achieve what I wanted to do. I've also worked on the code-stepper, which stole another chunk of the effort too. Now that I feel more comfortable with Clerk, next time should be smoother and more useful.

BTW, I've also proposed a talk for the Conj. around this, thinking of presenting the idea of Moldable Dev., the value of visualizing your problem domain, etc... And here's a small example I had in mind to show: even today, the algo generates partial-moves, which may push pieces off the board, and then a constraint predicate filters them... For some reason, it was surprising for me to see this on the code-stepper:

... which immediately challenged me: Should I even allow that to happen? should I treat that as an invalid state and thus not even generate such intermediate pmove? If you look at the code, there's even a function that does that already (current not used) which generates the initial pmoves preventing that to happen (instead of letting a latter filter to drop them)

That's really interesting.. in a typed language you'd think of constraining things such that invalid states are unrepresentable, but we have to account for the fact that ill-formed data can exist and even construct such data in order to unit-test our validation functions. But the question of whether and how the viewers should treat them gets blurry – should it be treated as undefined behaviour (anything goes) or should there be validation logic mixed into the viewer logic so the visuals can be used to track down bugs?

so... this might become another extra section of that notebook someday 🙂

I've definitely found myself on the latter side while writing exploratory viewers alongside exploratory domain modelling, I think that's one of the reasons for the tension – the viewer logic quickly becomes unwieldy and more complected than the actual domain code and then becomes a chore to maintain

The code stepper definitely seems worth making into its own library, I'd be interested to play around with it :) Right now in the walkthrough of (expand-pmove-rook-v1 pmove-1) it looks like there are a couple of buggy spots around bracket highlighting (steps 9.., 19..), and it's also strange that the function calls in (-> pmove :steps first) don't get stepped through

Those tabbed / side-by-side viewers also feel like something that should be in the standard library – like how Portal lets you interactively toggle between different views of the same data

yes, separating it is what I should work on next. And yes, those tabbed viewers are somewhat generic too

I love this!

Just read it. Fantastic work! 👏 It’s very well written. So good to see the code-stepper and the test viewer!

just noticed a few tiny things, first one being a clerk issue with how it breaks after the (, I’ll make an issue and see that we fix it.

the Closing Thoughts link at the very end of https://neuroning.com/boardgames-exercise/notebooks/walkthrough/ isn’t working for me

small typo ther instead of the in https://neuroning.com/boardgames-exercise/notebooks/walkthrough/#the-rook-v2 > 1. expands the pmove on the four offsets (directions) of ther rook

did you share this elsewhere? E.g. in #news-and-articles? Highly recommend giving it a read.

and if you have fresh memories about your experience in writing these clerk viewers, especially pain points, please do share them.

the code stepper sounds like a cool thing to extract to a different repo.

Thanks a lot!

Sure, I could probably do a write-up of my "lessons learned" working with Clerk... It was not easy for me to figure out how to do what I wanted to do (and still have many open questions). Would be happy to discuss

> the Closing Thoughts link at the very end of https://neuroning.com/boardgames-exercise/notebooks/walkthrough/ isn’t working for me Thanks! good catch. That's one minor pain-point: couldn't make links across notebooks to work consistently... sometimes they work when working live, but not after static gen, or the other way around

Oh wow, that looks amazing! Looking forward to read it!

Super nice work ❤️ 👌 And you also used our experimental test runner and viewer right? https://github.com/nextjournal/clerk-test 🙂. Would be curious to hear if that worked out of the box or what did you have change. Maybe no longer up-to-date with latest Clerk.

Thanks Andrea! Yes, I've copy&pasted that code (yours?) and did a very hackish non-generic modification to make it display the "boards" ... One of the many TO-DOs: go back to it and try to make it generic... (actually, maybe it already is and I didn't understand it)

no, you’re right, we probably need to allow viewer customization at the level of the test vars and dispatch to the viewer by name to allow to override it