The 12 stages of learning Clojure

In 2020, I've been on quite a learning journey. I joined a team where we write code in Clojure, a very different language from what I’m used to. It turns out writing Clojure is a very nice developer experience, but it could take a while to get it.

You might have to go through some (or all) of the 12 stages of learning Clojure.

😮
1. "I have no idea what I'm looking at."

😬
2. "Where does that code end? Where does it begin? Why are there so many parentheses?"

🤪
3. "I'm totally lost."

😳
4. "Will I ever learn? Am I smart enough?"

😭
5. "I will never learn. I'm not smart enough. I want ice cream!"

🤔
6. "Hmmm, wait a minute ... map, reduce, filter. This is something I recognize."

🙂
7. "Yes. Clojure, yes, yes."

🤯
8. "OMG, this language is so powerful. OMG, I even understand some of it."

🙃
9. "defn, keywords, multi-methods, macros, juxt, slurp, ha ha ha ha ..."

😀
10. "Pretty clean. Yeah, I've learned the keyboard shortcut to nicely format the code. And threading macros are nice!"

😍
11. "I ❤️ Clojure. Everything about it makes sense. It's is the language I've been searching for all my life."

🧘
12. "Empty your mind, be formless, shapeless - like water. Now you put water into a cup, it becomes the cup. You put water into a bottle, it becomes the bottle. You put it in a teapot, it becomes the teapot. Water can flow, or it can crash. Be water, my friend." *

You might wonder what stage I'm currently in. Well, probably somewhere between 🙂 and 😀.

Here's some of the sources that I have learned a lot from:

• Clojure for the brave and true
• Programming Clojure
• ClojureScript Koans
• Elements of Clojure
• Learn Reagent

I'm sure I will keep trying, failing, learning and mostly smiling in 2021 ✨

^{* Yes, Bruce Lee said that.}

The ZooKeeper's New Year's Resolution

(... will probably not be lose weight. Because it has already been fulfilled)

What happened during 2020?

The Node.js ZooKeeper Client - simply called zookeeper - have been released 5 times and the current version is now 4.7.1.

🎉 Packaging

The source code is packaged differently, making the footprint a lot smaller and the install process simplified. To summarize: the ZooKeeper lost weight.

🎉 Prebuilds make the install process really, really fast

The install process is faster than ever. If you are a Mac OS X or Windows user, there is no longer any need to build an AddOn during the install process. Everything is already included in the package, thanks to a cool tool called prebuildify. Linux user? Don't worry, the installer will quickly build a Native Node.js AddOn for the Linux flavor you are running. During 2021 we will probably include prebuilds for the most common Linux flavors.

🎉 TypeScript

TypeScript declarations makes the Developer Experience very nice. With type hints, function parameter docs and autocomplete.

🎉 async zookeeper

Promise based functions are the default.
await client.create(path, data, constants.ZOO_EPHEMERAL);

🎉 Same client for all platforms

The same version of the C Client source code is now used in Linux, Mac OS X and Windows 10 to build a Node.js native AddOn. Before that, there was an issue with Windows clients connecting to a ZooKeeper server v3.4.8 that made us add a workaround - reverting to a really old client version for Windows users. But that is now solved and all platforms share the same set of modern features. Yay!

🚀 What's next?

Adding support for the new node types introduced in Apache ZooKeeper server v3.5.5:
Container and TTL. The features will probably be released during January 2021.

🎉 Happy New Year! 🎉

Developers and their text editors

The text editor, or IDE, is probably the developers' best friend. Is the editor almost like a ... family member? You spend a lot of time with your text editor: writing, navigating and reading code. Just like a family member, a text editor can be a source of inspiration, annoying, joyful, difficult to figure out and probably something you will need a break from at times.

For a couple of months, I've been on quite a learning journey. I have joined a team where we write code in Clojure, a radically different language from what I’m used to. I also decided to try out a new editor: Emacs, radically different from tools that I am used to.

I still struggle with the context switch of copying some text from a browser (using the well known key combinations ⌘+c and ⌘+v) - to copy-paste in Emacs, using the Kill-ring-save (M-w) and Yank commands (C-y).

So why did I choose Emacs?

It is in fact a very good Clojure editor. There's a lot of really nice plugins and features for writing Clojure and ClojureScript. Also, compared to programming languages like Python or JavaScript, it seems there aren’t that many tools out there designed for Clojure development. Once you have the features and key combinations in place, Emacs is a very nice developer experience.

Clojure is a very nice developer experience. 💫

It turns out that Emacs also is really good for writing Python and JavaScript. I guess you could use Emacs for anything text based, but I'm not there yet.

Here's my current Clojure, Python and JavaScript friendly Emacs configuration that will probably be updated continuously as I learn more, and how to replace annoying text editor defaults.

Documentation: The Good Parts

Writing documentation is probably the most boring part of software development. As developers, many of us avoid it. We write docs only when someone else force us, twist our arms or assign us JIRA tickets.

- Was it the project manager, or maybe that senior tech lead guy with the massive beard that made you write the docs?

What I want to describe in this post isn't complex Word documents explaining some software. It isn't a guide on how to write something clever about a public FirstName property of a Person class.

It's about JavaScript and data types. Keeping it simple, and fun.

 

JavaScript is dynamic
JavaScript won't stop you from passing in whatever you want to a function, even when the code is expecting data of a specific type. It will crash during runtime instead, yes. When parsing or iterating something that cannot be parsed or iterated.

- No type checks for you!

This is also what makes the language very flexible. Simplistic syntax, functions as first class citizens and with a little less noise. There is no need for explicit data type declarations, generics or interfaces, making it easy to write code in less than 100 characters width. In fact, you will find yourself writing code in less than 80 chars quite often. In addition, having only one thread to worry about is a good thing (for most of us). And I believe the V8 engine is fast enough too.

- It would be nice if there was something that could let us have a little bit of both.

Did you say TypeScript?
TypeScript is cool. But I'm not sure it is the way to go for back-end code written for Node.js. Node.js itself is probably a bad choice if you are in great need of strongly typed language features on the server. Why not go for C# instead? 

If your code lives in the browser, well, that is something different. You are basically stuck with JavaScript for web development - whether you like it or not. TypeScript, or WASM, can probably help you - after some initial setup, headache & build scripts.

 
Have you tried JSDoc?
During my work on the Open Source project node-zookeeper, I have learned how JSDoc can help us make the JavaScript Developer Experience a lot better - without the headache. Your editor will give you hints and warnings about parameters and data types.

Here's an example:

/** @returns {number} */
function getRandom () {
    ...
}

With parameters:

/**
 * @param {number} minValue
 * @param {number} maxValue
 * @returns {number}
 */
function getRandom (minValue, maxValue) {
    ...
}
 
In the example, documentation is used only for describing the data types of input parameters and the return type. Nothing else. I would recommend you to try hard and refactor the actual code, making additional comments not needed. Is the function name getRandom good enough?

- Maybe I should add some comments to the code here?

(don't do it)

Your editor is smart
Your IDE or editor will figure out the JSDoc syntax, even for custom type definitions. Custom type definitions are for objects - custom data types - that cannot be described as built in strings, booleans, numbers, objects or arrays.

Another example, this one is from the typedefs.js of the node-zookeeper project, describing a ZooKeeper node changed callback:

/**
 * Watch callback
 * @typedef {callback} watchCb
 * @param {number} type
 * @param {number} state
 * @param {string} path
 */ 

The type definition for the watcher can be referenced in the code like this:
/** @param {watchCb} callback */

The node-zookeeper project has a typedefs.js file in the root folder. A smart IDE, like WebStorm, will parse it and use the type definitions to give you and your coder friends a nice developer experience.

When dynamic isn't good enough, use JSDoc. But be careful, use it only when needed. Or else, you will be stuck in the Documentation Swamp.

Experimental Node Mode

The latest Long-Term Support (LTS) version of Node.js has support for writing and consuming modules in ECMAScript style - without any tools or frameworks. That is good news! I have mostly been writing back-end code using the CommonJS standard, but have always preferred the ECMAScript way, commonly used in front-end development with tools like Babel.

Now, with Node.js 12, there is native support for ECMAScript modules. But it has to be manually enabled, by using the '--experimental-modules' flag.

The current version - Node.js 13 - doesn't need a flag to enable ECMAScript modules. Great! It is on by default. But the runtime will log a message on startup, a warning that the feature is not ready for production yet. Maybe we can expect it to be a default setting, without experimental warnings, in the next LTS later this year?

I have tried out ECMAScript modules in Node.js, using the experimental flag and the type: module in package.json.

Import tooling support, not perfect, but good enough.

Cool, but not perfect yet
I ran into issues when writing & running unit tests. My favorite unit testing library is tape, but it doesn't support ECMAScript modules natively:
Must use import to load ES Module

What about the AVA test runner ? No native support yet. Mocha? I couldn't find any info about it, but tests won't run.

Tape is just JavaScript 👍
It is convenient, but tape unit tests doesn't require the built in runner. Both AVA and Mocha need a runner. Using tape, you can run the unit tests just like any other JavaScript file with the Node.js CLI.

Don't try this at ... work?
Besides that using a default unit testing runner usually is a good thing, there's also a huge drawback with the experimental & non-standard approach that I describe in this post. The node command will run a single file only. 👀 

But, hey, we're in Experimental Mode right! A workaround would be to execute a custom runner containing all our unit tests. Just don't forget to add every new file to it.

"scripts": {
    "test": "node --experimental-modules test/run.js | tap-spec"
}

(from the script section of package.json)

The test/run.js file:
import 'path-to-unit-test'
import 'path-to-another-unit-test'


Try this at home, folks. Don't try it at work (yet). 🏡