Your Coding Tutorial Might Need Some Refactoring

Both code and coding tutorials can be refactored

At some point in your coding career, you’ve probably come across a piece of spaghetti code that’s not so reader-friendly. It needed some refactoring.

Similarly, you’ve probably also come across a coding tutorial that’s not so reader-friendly. Maybe you wanted to learn a new language, library, or framework, but the tutorial you found made you more frustrated than before.

But they can be improved. As someone who’s written many coding tutorials, I realized that most coding tutorials can be refactored to be more reader-friendly—just like refactoring code.

However, while many programmers have written guidelines on how to refactor code, guidelines on how to refactor coding tutorials are rare.

So, in this article, I’ll share six opinionated tips on refactoring coding tutorials. I’ve used these techniques on my own tutorials to make them more reader-friendly. Here’s the list:

1. Make code samples mobile-ready
   
2. Prefer minimal code samples
   
3. Prefer practical code samples
   
4. Fail fast
   
5. Use themes, analogies, and quizzes
   
6. Add a thoughtful touch
   

Let’s take a look!

Refactoring Tip 1 of 6:

Make code samples mobile-ready

Take a look at the code below. It’s in TypeScript, but don’t worry if you don’t know TypeScript. I used it for my tutorial called “TypeScript Tutorial for JS Programmers Who Know How to Build a Todo App”:

type Todo = Readonly<{
  id: number
  text: string
  done: boolean
  place: Place
}>

Did you notice that the above code is formatted to fit on a small screen? Because each line length is short (max 31 chars), you can read it without side-scrolling on most phones.

If the above code was formatted in a single line like below instead, you’d have to side-scroll or wrap text on a small screen, which hurts readability.

type Todo = Readonly<{ id: number; text: string; done: boolean; place: Place }>

Here’s another example I used for my tutorial called “TypeScript Generics for People Who Gave Up on Understanding Generics”. This is good formatting ( fits on a small screen):

function makePair<
  F extends number | string,
  S extends boolean | F
>() {}

And this is the same code in BAD formatting ( doesn’t fit on a small screen):

function makePair<F extends number | string, S extends boolean | F>() {}

So, here’s my first refactoring tip: Make code samples in your tutorials mobile-ready.

You can ensure this by keeping line length short. I try to keep it under about 50 characters (at 14px font size). I use Prettier with custom printWidth to automate this (my .prettierrc is here).

Here are some other techniques:

• Prefer shorter variable names (but don’t sacrifice code readability).
• If you can customize the CSS, use narrow coding fonts. I use Iosevka—it’s slim and looks great. You can also tighten letter-spacing to fit more characters.
• If you want code samples to have longer line length on a larger screen, you can use Prettier in the browser to dynamically adjust line length based on window width.

Why is this necessary? Because many people actually read coding tutorials on their phones.

You might be tempted to assume that your readers will read (and follow along) your coding tutorial on a computer. But that’s a bad assumption.

In the past, I’ve used Google Analytics to track desktop vs mobile usage on my coding tutorials. Even though my tutorials are meant to be done on a computer, surprisingly many people accessed them from a mobile device.

This is because many people discover coding tutorials while using a phone to browse Twitter, mailing lists, and online forums.

That’s why mobile reading experience is important. If you can easily read all the code samples on a phone, you might be able to finish the tutorial without pulling out your computer. Sometimes you need to follow along on your computer to fully understand the content, but that’s not always the case.

The bottom line: Assume that people will discover your coding tutorial on their phone and try to deliver the best possible first impression.

Refactoring Tip 2 of 6:

Prefer minimal code samples

As of writing, the following code appears on the official TypeScript handbook (which is written in a way that’s both a tutorial and documentation). And the handbook uses this code to explain how to use a particular TypeScript keyword/operator.

Question: Can you tell which keyword/operator is being explained through this code? Hint: It is one of the keywords/operators used in the code. (You don’t need to know TypeScript—just guess!)

function extend<First, Second>(
  first: First,
  second: Second
): First & Second {
  const result: Partial<First & Second> = {}
  for (const prop in first) {
    if (first.hasOwnProperty(prop)) {
      ;(result as First)[prop] = first[prop]
    }
  }
  for (const prop in second) {
    if (second.hasOwnProperty(prop)) {
      ;(result as Second)[prop] = second[prop]
    }
  }
  return result as First & Second
}
class Person {
  constructor(public name: string) {}
}
interface Loggable {
  log(name: string): void
}
class ConsoleLogger implements Loggable {
  log(name) {
    console.log(`Hello, I'm ${name}.`)
  }
}
const jim = extend(
  new Person('Jim'),
  ConsoleLogger.prototype
)
jim.log(jim.name)

Answer: The official TypeScript handbook uses the above code to explain how to use the “&” operator in TypeScript.

But it’s hard to tell! If you look at the code again, only the highlighted part below is related to the “&” operator. There are too many other keywords that are just noise (e.g. Partial<>, hasOwnProperty, as, constructor, public, interface, void, implements, prototype, etc). You also need to pause and read carefully to understand what’s going on, even though most of the code isn’t directly related to the “&” operator.

function extend<First, Second>(
  first: First,
  second: Second
): First & Second {
  const result: Partial<First & Second> = {}
  for (const prop in first) {
    if (first.hasOwnProperty(prop)) {
      ;(result as First)[prop] = first[prop]
    }
  }
  for (const prop in second) {
    if (second.hasOwnProperty(prop)) {
      ;(result as Second)[prop] = second[prop]
    }
  }
  return result as First & Second
}
class Person {
  constructor(public name: string) {}
}
interface Loggable {
  log(name: string): void
}
class ConsoleLogger implements Loggable {
  log(name) {
    console.log(`Hello, I'm ${name}.`)
  }
}
const jim = extend(
  new Person('Jim'),
  ConsoleLogger.prototype
)
jim.log(jim.name)

So, in my opinion, the above code sample is NOT a great way to explain how to use the “&” operator in TypeScript. It does show a few places where the “&” operator can be used, which is good, but it could have been done without adding so much noise.

If I were to explain how the “&” operator works in TypeScript, I’d refactor the earlier code as follows—it basically does the same thing in a simpler way. You don’t need to understand TypeScript to know that this is more minimal and focused on explaining how to use the “&” operator. The amount it takes to understand this code is also much shorter.

type Person = { name: string }
type Loggable = { log: (name: string) => void }
// Use & to make jim BOTH Person AND Loggable
const jim: Person & Loggable = {
  name: 'Jim',
  log: name => {
    console.log(`Hello, I'm ${name}.`)
  }
}
// "Hello, I’m Jim."
jim.log(jim.name)

If you want to talk about more advanced usage, you could add the advanced example AFTER my simple example.

What I want to say is: Prefer minimal code samples, at least initially. If you’re trying to teach a new concept (let’s call this “X”), just focus on X in the code sample and don’t add too much extra stuff. Add extra stuff only (1) after you showed a simple example and (2) when it really helps the reader’s understanding.

Minimal reproducible example: When you ask a question on StackOverflow or file an issue on GitHub, you’re often asked to create a minimal reproducible example. Your code needs to be as small as possible, such that it is just sufficient to demonstrate the problem, but without any additional complexity (Wikipedia’s definition).

You should use the same principle when writing code samples for your tutorials. Ask yourself: Can I make this code sample more minimal while maintaining the learning experience?

Refactoring Tip 3 of 6:

Prefer practical code samples

As of writing, the following code appears on the official TypeScript handbook (right after the example we showed earlier). And the handbook uses this code to explain how to use the union operator in TypeScript, which is the “|” symbol highlighted below.

/**
 * Takes a string and adds "padding" to the left.
 *
 * If 'padding' is a number, then that number of
 * spaces is added to the left side.
 *
 * If 'padding' is a string, then 'padding' is
 * appended to the left side.
 */
function padLeft(
  value: string,
  padding: number | string
) {
  if (typeof padding === 'number') {
    return Array(padding + 1).join(' ') + value
  } else {
    return padding + value
  }
}

In TypeScript, you can write number | string to specify that a parameter can either be number OR string. So in this case, the second padding parameter can be either number or string.

• If padding is number, then that number of spaces is added to the left side of value.
• If padding is string, then padding is added to the left side of value.

// If the second parameter is number, then that
// number of spaces is added to the left side
padLeft('Hello world', 4)
// → "    Hello world"
// If the second parameter is string, then
// that string is appended to the left side
padLeft('Hello world', 'Jim: ')
// → "Jim: Hello world"

Now, a question for you: Is padLeft() a good example to explain how the “|” operator works in TypeScript?

I’d say NO—it’s NOT a good example. You don’t need to know TypeScript to see why.

Take a look below and ask yourself: Would you EVER use padLeft() for the case where the second parameter is string?

// If the second parameter is string, then
// that string is appended to the left side
padLeft('Hello world', 'Jim: ')
// → "Jim: Hello world"
// Ask yourself: Would you EVER do this?

You probably would not. It just does simple string concatenation in reverse. You probably would just use other standard ways to concatenate strings, such as 'Jim: ' + 'Hello World'. There’s no good reason why padLeft() should support the second string parameter.

The bottom line: padLeft(value, padding) is useful if padding is number but is pretty useless if padding is string. So setting padding’s type as number | string is not useful—it could just be number. That’s why this is NOT a good example.

So, here’s my third refactoring tip: Prefer practical code samples. Avoid showing code no one would write. If you’re trying to teach a new concept (let’s call this “X”), come up with a practical code sample where X is actually useful in solving the problem.

By showing a practical example, readers will understand why X is worth learning. If you show them a useless example, they’d think: “What’s the point of learning X?”

Example: If I were to explain how to use number | string in TypeScript, instead of the earlier padLeft() example, I would use the following paddingLeftCss() function. The name is similar, but this one is used to generate a CSS padding-left string:

function paddingLeftCss(val: number | string) {
  if (typeof val === 'number') {
    return `padding-left: ${val * 0.25}rem;`
  } else {
    return `padding-left: ${val};`
  }
}
// padding-left: 0.25rem;
paddingLeftCss(1)
// padding-left: 0.5rem;
paddingLeftCss(2)
// padding-left: 10%;
paddingLeftCss('10%')

paddingLeftCss() can take a number or string:

• If it’s number, it returns padding-left CSS that’s a multiple of a predefined spacing unit. In this case, 1 = 0.25rem, 2 = 0.5rem, etc. This would be helpful for visual consistency when designing UI.
• If it’s string, it just uses that string as padding-left.

This is similar to how UI libraries like styled-system work. In other words, it’s a practical example. It actually makes sense to have the parameter be either number or string, unlike the previous example.

To summarize, always ask yourself: Is my code sample practical? Would anyone ever write code like this?

Refactoring Tip 4 of 6:

Fail fast

One of the best ways to capture your reader’s attention is to FAIL. When things don’t go according to plan, people will pay more attention than when everything goes smoothly. Use this to your advantage.

Furthermore, it’s more effective if you fail fast. Try to show a failing scenario as early as possible in your article. By doing so, you’ll be able to capture your reader’s attention right off the bat.

For example, on my TypeScript tutorial, I start with an example where, if you run the code, the actual result is different from the expected result (failure). Then I talk about how to prevent failures like this using TypeScript’s features.

Here’s a simple technique you can use. If you want to teach a new concept (let’s call this “X”), start with a concrete scenario where things fail or aren’t ideal when you don’t use X. Then, use X to solve the problem. Your readers will pay more attention and also understand why X is worth learning.

I used this technique on my TypeScript generics tutorial. Early in the article, I attempt to solve a problem that can only be solved by generics…without using generics. Of course, I fail. Then, I use generics to successfully solve the problem.

In a way, this is similar to test driven development (TDD). In TDD, you write a failing test first, and after you watch it fail, you try to make it pass. Similarly, in a coding tutorial, it’s more effective if you show a failing example first and have the readers watch it fail.

It’s tempting to be lazy and skip writing a failing test in TDD. Similarly, when writing a coding tutorial, it’s tempting to skip showing a failing example and just start with a successful example. But resist this temptation—failure is your friend in expository writing.

The bottom line: Double-check to see where the first failing example appears in your tutorial. If it’s missing, add one near the beginning.

Parting thoughts

In 2017, Dan Abramov from the React.js team gave an excellent talk called “The Melting Pot of JavaScript”. He talked about how one should approach building tools (like React, create-react-app, etc) that many beginners/newcomers use. Here’s his quote:

If you’re building tools like me, there’s this fact that we have become the new gatekeepers to one of the largest programming communities in the world.

And this is scary stuff. Because it means that every time our tool prints an incomprehensible error message, somebody somewhere decides that they’re just not cut out for programming. And this is a big responsibility.

[...] If you’re a maintainer of an open-source project it is invaluable to go out there in the field and see what they struggle with as they try to use your projects.

And if you think improving newcomer experience is polish, it’s not polish. If you go out there in the field you will see that it makes a real difference in people’s lives, and what they can learn, and what they can build with it. So it’s not just polish. Take this seriously.

I think his quote applies not just to coding tools, but also to coding tutorials.

You don’t have to follow all the guidelines I mentioned on this page. Sometimes you have to break the rule when refactoring code—and the same is true for refactoring tutorials. But do try to revise as much as possible. As the saying goes, “Writing is rewriting”.

You can click here to tweet this article.