clj-refactor cheatsheets

Summary: I've made some cheatsheets to help me learn clj-refactor, some Emacs software that helps you make systematic changes to code.

Wow, do I love me a good cheatsheet. "Cheatsheet" reminds me of my days at school where some kids would write in tiny writing to try to cram as much text on a little sheet of paper as possible. That may help cheat on a test, but it's not going to help you learn.

The purpose of a cheatsheet for learning is to decrease the cognitive burden of the task. You've only got so much mental capacity for new things. You don't want one of your precious slots dedicated to remembering a keystroke for a new Emacs command---not while you've got 10 other things to learn. You want the cheatsheet to take care of that for you and free up that slot. Then you can practice deliberately.

However, if the cheatsheet is full of stuff, you've introduced another burden. Now you have to search through all of that stuff, most of which is not immediately relevant, to find what you need right now. If the search is too arduous, you'll have to free up some slots. And so you forget what you were trying to do in the first place.

So there's this delicate balance of enough information with easy access. What I see a lot of in cheatsheets I find online is that they try to cram everything onto one page, like the desperate student the night before the test. The cheatsheet becomes an exercise in convincing the word processor that it can all fit. The actual user is forgotten.

Here are my design principles for a good cheatsheet:

• Readable at a distance

  You should be able to read it on the wall behind your screen. You're probably already using both hands to type, so you don't want to have to pick it up, rifle through papers, scan with your finger, etc.

  This means large fonts, lots of whitespace, and clear organization.

• Focused

  The point is to capture a few related things that you want to practice together. Things you're not trying to lear

  n can wait for another sheet. Things you already have mastered don't need to fit either.

• Terse

  This is a quick reference, not an explanation. Key points can be called out, but a lot is left unsaid.

• Evolving

  These are not static documents. They are learning aids and should be adapted to your needs. Have you mastered one of the things? Remove it. Is there something you've left out? Add it. Keep it relevant and you'll want to keep referring to it.

All this is to say that I've made my own cheatsheets for learning clj-refactor. I gave it a shot a couple of weeks ago and I realized that to really make use of the tool, I'd have to get fast at it. There's no point in using a fast tool if I slow it down. But there are lots of available refactorings.

I started using clj-refactor with these cheatsheets and it's amazing what refactorings are available. I'm constantly surprised by how smart they are. For instance, the cljr-extract-function command creates a new defn, adds the expression to the body, finds all free variables and makes them parameters to the new function, adds a "tabstop" to type the name, and one more Tab will bring you back to where you were. This is cool stuff.

If you're interested in the cheatsheets (4 in total) with big fonts, a little editing (only relevant refactorings), and terse information, please sign up for the mailing list. Once you do, you'll get access to the Clojure Resource Center where these cheatsheets and more are available.