Newcomers to Clojure so frequently ask this question that an FAQ/Guide is being discussed, to add to the Clojure website. See Issue #586: Add FAQ or guide for example projects. Please add your thoughts to that ticket!

This post is my (opinionated) take on it. I struggled a lot with this too. I still do from time to time, in unfamiliar territory, and these days I feel like I’m in unfamiliar territory a lot. Various Clojurians — individuals and groups — have been producing so much creative, diverse work over these last few years that keeping up quickly became impossible!

No doubt this surfeit of creativity intimidates newcomers. The strange ideas, lingo, thinking, and writing espoused by Clojurians can seem so very alien. But despair not, for Clojureland also has a surfeit of friendly, helpful people. And very many of our codebases are small! You will be able to read them! And get help if you get stuck!

This post explains what I believe I’ve done subconsciously over the years. It is as much an answer for somewhat experienced me as it is for the relative newcomer you!

• A quick motivating example
• Heuristics to choose a project to read
• Effective way(s) to read a project
• Suggested projects with short reasons why to read
• Library maintainers: Would HOWTOREADMEs make sense?

Or, the one in which we hand-craft nano Unix tools using Bash functions.

As we saw in the previous post, functions obey stdio and we can mix and match them with built-ins (grep, sed, cat etc.) and other installed tools (like jq, pandoc, babashka etc.). We used functions to name parts of Douglas McIlroy’s pipeline and mess around a bit.

I tend to make libraries of pure functions that I can source in shell sessions and use just like any other shell tool, complete with tab-completion. e.g. bash-toolkit and shite.

Now we step back and try to build good intuitions about

• what functions are
• how to design good functions
• how to design programs with functions
• how to name them :)

You won’t know of Org Mode if you live a normal life. This page has pictures that will help you visualise it.

It is a decidedly un-sexy under-marketed weirdly niche tool for note taking (and a lot more). “Your life in plain text”, they say.

Yet, I find myself telling people that they will have to pry it from my cold dead hands. Which befuddles me. Why, as an ingrate software nerd who has soured on software technology —talk about biting the hand that feeds— do I evince such strong sentiment about a software program?!

Also, plain text? In 2022?!

Well, join the wonder club. I’ve been wondering the same thing!

With further ado, I will:

• illustrate my org-mode use with real examples
• describe my “what, why, and how” in generally applicable terms
• discuss some common objections and concerns
• offer some shiny brain-food for your imagination

Also nerd alert. I can’t remove some technicalities without also dumbing it down and doing your intelligence a disservice. Email me if you need help.

Take what is useful and discard the rest!

FizzBuzz is everywhere. Every programmer passes through its rite of passage, or at least bears witness to another. Over the years, many gentlenerds have taken it upon themselves to discover ever new ways to incant those hoary symbols.

I hereby enjoin these few drops of Clojure to that roiling ocean of FizzBuzzery.

The brainwave here is to (mis)use the feature set of Clojure and its standard library to cook up as many ways to encode FizzBuzz as one can muster (or steal). If all goes well, this post will receive many updates. If it goes really well, all sorts of bad ideas and clever foot-guns will be discovered and used.

The creative constraint is this: any FizzBuzz, however terrible or hilarious, must also be useful. It should have reason to exist and should reveal some real-world Clojure thinking.

That means no FizzBuzzEnterpriseEdition but also no Dylan Beattie’s brilliant FizzBuzz in RockStar. So sorry!

Or, the one in which we “take apart” Douglas McIlroy’s pipeline from 1986.

Doing so teaches an object lesson about the essence of modular, composable, functional architecture. And things start to really heat up when it dawns on us, how a good set of standard parts can be used to express totally different ideas just by composing them in different ways.

(Edit 2022-03-10: speaking of lessons, how about the one in the appendix?!)

“Designing is fundamentally about taking things apart. It’s about taking things apart in such a way that they can be put back together. i.e. Separating into things that can be composed.”

• Rich Hickey, “Design, Composition, and Performance”, 2013

tr -cs A-Za-z '\n' | tr A-Z a-z | sort | uniq -c | sort -rn | sed 10q

• Douglas McIlroy, Communications of the ACM, 1986

• The Pipeline that Douglas Built
• Take Apart! Semantics/Idioms -> Functions
• Play! Semantics -> Functions -> “Ooh, what if I…"
• Compose Again! Semantics -> Functions -> Play -> Grand New Pipeline
• Addendum: Remarkable aspects of Doug’s O.G. pipeline
• Appendix: an unexpected masterclass!
  • The danger lurking in the pipes
  • Backstory
  • Postscript

Previously: Shell ain’t a bad place to FP: part 0/N

This primer is for people like me, who long dreamed of lovingly hand-crafting our own home on the Internet. We would make it ultramodern yet ultralight, simple yet beautiful. Something not WordPress because that’s so last century. (Seriously, just go to WordPress.)

No. We were committed. We would do it for the sake of craftsmanship and the environment and World Peace. And that’s how we found ourselves awake at 2 A.M., having absurd conversations ¹ with Distant Internet Strangers…

Throwback: Jan 2018.

I learned of Dismal Arithmetic from @rdivyanshu who posed it as a programming problem in a Slackroom of local gentlenerds.

As the linked paper describes it:

Dismal arithmetic is just like the arithmetic you learned in school, only simpler: there are no carries, when you add digits you just take the largest, and when you multiply digits you take the smallest. This paper studies basic number theory in this world, including analogues of the primes, number of divisors, sum of divisors, and the partition function.

I thought it might be fun to implement it in APL for kicks, but I wrote it in Clojure first, because I wasn’t sure of my APL-fu. And I’m glad I wrote the Dyalog APL version because I learned something about trains, and also because I stumbled on the idea of “inverse of a function” which melted my mind a bit.

• Examples of Dismal Addition and Multiplication
• Dismal Arithmetic in Clojure
• Dismal Arithmetic in Dyalog APL
• Addendum: The ⍣ of inverse

Or, Supremely Functional Bash Programming, an exploration in N parts…

Once upon a time, while fiddling with a log processing shell pipeline, it hit me that the UNIX Way is a Surprisingly Functional Way, and so Functional Programming (FP) and Bash must be a natural fit. They fit. The world was never the same again.

Now I believe it so much, that I will go on a limb and assert that it is highly inappropriate to write imperative-style Bash when we can just as easily write supremely functional Bash. Why? Because it makes for supremely better Bash (more reusable, more composable, more scalable, more enjoyable).

Yes, I truly believe.

Yes, I’m sane.

No? Well OK, humour me…

• Obligatory mea culpa
• An outline of the “N” parts
• Prelude: Seeing the UNIX tools philosophy as a functional design philosophy
• “Screw that, show me your code”

In which we ponder the Functional Nature of Life, The Universe, and Everything. Please feel free to follow through the weeds, or jump straight to the bottom for my 2 nano BTC on the matter. (Or my current state of mind, at any rate.)

Disclaimer: I live in the Land of Lisp, meditate in the Church of Alonzo, and am ever-wary of The State. Only converts might find some entertainment value.

“For the love of State is the root of all evil: which while some coveted after, they have erred from Lambda the Ultimate, and pierced themselves through with many sorrows."

• Is it already suffusing your very being?
• Is it Mathematics?
• Is it being “declarative”?
• Is it being “data-oriented”?
• Is it about “Statelessness”?
• Is it about “managed” environments?
• Is it about following some discipline, and maybe automating it?
• My 2 nano BTC on the matter

This is how I struggle from time to time. It is not pretty. These days it’s been a lot more. Thankfully, it is not a constant. Instead of reading this, you should want to listen to Alain de Botton.

• on Pessimism
• on Love
• on an Emotional Education

For here lies melancholy that I put to paper from a particularly deep hole, not too long ago. It may ruin your day, or it may make you feel a little bit understood about your dark moments. And it—unlike Alain’s teachings—will certainly not help you find a way through.

Your mileage will vary.

The premise:

-> People create culture.

-> Culture shapes values.

-> Values inform strategy.

-> Technology is Strategy actualised.

Throwback, June 27, 2020.

Every so often, I want to avoid opening a website in a browser, for … reasons.

Curl alone presents too much html. I want to try and read stuff.

Today, I was playing with Igor Chubin’s awesome terminal services (wttr.in, cht.sh etc.), and it hit me:

“WAIT, there’s pandoc, what if I just … "

First off, what even is Quality?

All things emerge, change, and die. I think Quality is the experience of the process. The idea of Good Quality essentially boils down to performing the process with grace, and leaving the place better than we found it.

Further, the process of emergence and change—i.e. living—is also the process of dying. It follows that to think clearly about the Quality of the former one must think clearly about the Quality of the latter. The saddest way it can unfold is a slow painful degradation without healing succour meaning or hope. The proverbial death by a thousand cuts. I hope you never witness such a passing, even from afar.

Ok, that got dark fast, and if we’re not careful, we will produce a 300 page Zen dialogue on Motorcycle Maintenance. So we will distract ourselves with the much smaller, lighter—and I’d argue, even pleasant—task of contemplating Quality of software products.

None of what follows is novel, but I feel the message and its surrounding context bears repeating, because if it is not obvious already, software fails us all the time. Far too often with terrible consequences.

• What is the nature of software products?
• Whom to hold responsible for Software Quality Assurance?
• Why?
• Is it different for different kinds of products?
• How to destroy Quality?
• How to create Quality?
• The first skill is to learn to suffer constructively.
• Caveats, mea culpa, etc.

A friend and I were chatting recently about speaking at conferences. Now this person is smart and I’ve learned a thing or two from his in-depth engineering blog posts. Yet there he was, telling me I’m so super good at communicating ideas (implying he’s not so super good), and besides he has nothing to say worthy of a conference talk.

Huh?!

Uncalled for praise is jarring, but I took it—2021 was heartless, OK? Still, the subtext of magic bothered me. That I am somehow special. A born natural. So I told him my secret formula. And now I’m telling you.

Here is how to be a totes natural conference speaker…

I’ve long struggled with the Technical Debt metaphor. It was immediately useful when I first heard it. I still think it is useful, albeit as a starting point. The more I worked with software, the more infuriatingly incomplete it started to feel.

Some years ago I found myself in a rabbit hole, researching the 2008 financial crisis. It reminded me of other insane stories like Knight Capital, and further back, about how Enron imploded (because Enron India’s meltdown was shocking, and destructive. And because a dear friend, in his past life, was on the team at Lehman Bros. that structured financing for Enron India. So come 2008, when Lehman imploded, I got to hear about the hard-chargin' super-leveraged risk-takin' days from someone who was there in the early part of the so-called Dick Fuld era. It was all very fascinating, but I digress…).

Down in the rabbit hole, a slow realization began.

One source of my unease is that I think discussions of Technical Debt don’t sufficiently examine the nature of the Risk of the underlying challenge. The other is that the concept skews and pigeonholes the Responsibility part of the underlying challenge. Here’s what I’m thinking.

• Framing pigeonholes Responsibility.
• Software debt packages risk. We need better mental models of that risk.
  • Software debt risk perception is muddied by personal bias.
  • Software debt is rooted in complexity. We abhor complexity.
  • Software debt is inevitable.
  • Software debt always compounds.
  • Software debt is layered.
  • Software debt is networked.
  • Software debt is like a complex opaque financial derivative.
• 1,000 words in 1 picture: xkcd summarizes it best.
• Stories of Debt and Destruction

Note: In this post, I have software organisations in mind, viz. ones that exist mainly because of the software they make and ship (whether priced or gratis).