Programming Tutorials Should be Vaguer

The basic template for programming tutorials is:

  1. An introduction with a motivating example
  2. Step-by-step how-to style instructions with code
  3. Conclusion

But, if the way to learn programming is to write programs, this template breaks down at step 2. At the end of the tutorial, you have working code, but since your brain was engaged in reading and typing (or copying), it’s hard to absorb the information. I know that when I have “done” tutorials, I didn’t really learn the material in a way where I could do it on my own later.

So, perhaps tutorials shouldn’t give you all of the code, but instead provide enough information for you to write it yourself.

For example, here’s a code sample from a tutorial I wrote about GameplayKit:

enum GameOutcome: String {
    case win
    case reset
}

Instead of showing this, I could have written: “Declare a string-based enum named GameOutcome with two cases: win and reset.” There could have been a button that revealed the code.

Another way would be to use Steve McConnell’s coding technique from Code Complete. He suggests writing the comments first and then writing the code beneath (and between the comment lines), so like this:

// GameOutcome is an enum of the possible final states: win and reset.
// It needs to be a String-based enum because we use the
// raw value in GameplayKit methods that take an AnyObject.

This really only works for very simple code (I know because I tried to write the above example for more complex samples and couldn’t). A tutorial like this would get the reader playing instead of reading and help them practice composing code instead of copying it.