Code on slides

There can be a lot of value in using code examples in a slide presentation, but the pain of incorporating them can create a powerful incentive to use as few as possible: manually marking up syntax, dealing with alignment issues, and working around automatic typographical features that are inappropriate for code can add up to a lot of unnecessary work. This post includes some workflows I’ve used to streamline adding code to slides and presenting effectively with code. I’ll demonstrate techniques in the context of the tool I use the most (Apple’s Keynote), but everything should be applicable to other slide presentation systems as well.

When (and why) to present code examples

Before you worry about how to get code excerpts on your slides, consider what you’re trying to accomplish by putting code before your audience. The cases where it makes sense to share code are actually fairly narrow, since your audience is not likely to be uniformly comfortable with the language, frameworks, and concepts you’re talking about (or uniformly engaged with your presentation). Furthermore, any attention that your audience devotes to reading and trying to understand code on your slide takes away from their bandwidth to listen to you.

I’ve found three kinds of situations in which code is especially useful and successful in slide presentations:

1. Walking through a command line invocation, API call, or short function to build up an explanation one clause at a time or to call out potential pitfalls. In this case, being able to highlight indivdual parts of the excerpt as you explain them will make it much easier for your audience to follow the explanation.
   
2. Explaining low-level behavior or transformations in the context of high-level code. I used this technique regularly while teaching CS1 to show an evolving memory graph alongside a function that allocated memory and manipulated pointers. It’s also useful to show the details of how a runtime will execute or schedule high-level code, e.g., by showing the computation graph that is built up from various function calls in a framework like Spark.
3. Rhetorical stunts, in which the presentation of the code is evidence supporting an argument and in which the code isn’t actually meant to be read (or read carefully).¹ Sometimes, this can be a positive argument, in which the brevity and elegance of an implementation is the point rather than details of the implementation itself. At other times, it’s a negative argument, for example, that involves showing the prolix YAML specification necessary to configure a given tool or framework and wondering aloud about the cardinality of its target audience.

Walking through key points of a machine learning technique in the context of a basic implementation

Showing how a runtime scheduler builds up a computation graph from API calls

A verbose code excerpt that accomplishes a simple task can be a good way to demonstrate accidental complexity even if the code isn’t meant to be read.²

When explaining an algorithm by highlighting different parts of a function, it is less important that the audience reads and understands all of the code than it is that the presentation is able to convey the basic ideas behind the algorithm or technique in a meaningful context.³

There are real benefits to including actual source code in your slides, but there are also potential drawbacks. Most importantly, it is easy to overestimate any audience’s capacity to follow even a moderately-complex code example, so it’s best to consider what you’re trying to accomplish by projecting code on a screen in a dark room and whether or not you might be able to meet the same goal more effectively in a different way. In the rest of this article, we’ll assume you’ve decided that showing code is the best way to convey something important to your audience and are focused on the mechanics of incorporating code into your presentation.

Automatically typeset formatted code examples

I use Andre Simon’s highlight CLI utility to quickly typeset formatted code snippets. highlight will render its output in several formats, but RTF is usually a good choice if you’re going to be pasting in to a GUI application like Keynote. I use the following shell function so that I don’t have to look at the help text for highlight every time I start developing a new presentation.

highlight-syntax() {
    H_SYNTAX=${1:-python}
    H_FONT="Fira Code"
    H_SIZE=36
    H_FORMAT="rtf"
    {
        pbpaste |
        highlight --syntax $H_SYNTAX -k "$H_FONT" -O $H_FORMAT -K $H_SIZE | 
        pbcopy
    }
}

1

If you use a language other than Python most often, change the default language here.

2

Adjust the font family and size to your preferences. I find that 36pt is usually pretty good for my slides and code.

3

If you aren’t on a Mac, replace pbpaste and pbcopy with appropriate commands to access your clipboard. For example, on Linux, xclip -o -sel clip and xclip -sel clip, respectively, should work.

An underrated advantage of pasting in formatted code is that your presentation tool is much less likely to replace your straight quotation marks with curly quotes, or your hyphens with en-dashes.

Call out code while you present

If you have more than a few lines of code, your audience will probably appreciate some indication of what to focus on while you explain it. I’ve tried a few techniques in the past: highlighter-style markup, callouts with arrows, and varying opacity. Each can be useful, but I find myself using these roughly in order of the complexity of the code I want to discuss.

The first two techniques are great for annotating relatively simple code fragments, and we’ll discuss them now. The animated example here shows both highlighter-style markup and text callouts, although I often use the highlighter style without text callouts. I prefer to make slides that support a presentation (rather than slides that can serve as a standalone artifact) and the extra text for callouts sometimes just adds clutter.

Drawing highlights and callouts on relevant parts of a formatted code excerpt

Most presentation software will let you draw and style arbitrary lines, which is usually sufficient for drawing highligher marks on your code. I use a natural-media style stroke and one of the colors I’m using elsewhere in the deck, but at 50-70% opacity. Since most presentation software does not support alternate blending modes for partially-opaque objects, it’s best to move the line object beneath the code block so as not to impact the color of your text.

Styling a line with a marker stroke style in orange at 70% opacity

Important

You may have several options for natural-media stroke styles. Choose the one with the simplest shape that serves your aesthetic purpose. Simulations of rough-edged strokes, like paintbrush, crayon, pastel, or charcoal styles, can generate many complex shapes in rendered output and dramatically increase the size of a PDF copy of your deck.

Align code clauses when using builds and fades

Sometimes you’ll want to build parts of a code excerpt in or out in order to explain them one at a time, to show potential incremental refinements, or to emphasize the similarities between several related techniques. Since you’re almost certainly typesetting code examples in a monospace font, aligning code that builds in is easier than, for example, aligning prose might be.

Your presentation software probably has “smart guides” that will show you when an object is the same height or width as another, or when two objects share an edge or a center line. If you make multiple code blocks that are all the same size but a subset of your content, you can work with these guides rather than against them and make it easier to align your code as it builds in. I usually do this by copying the rendered code block but replacing some of the code with blank lines or transparent text, as in the following example:

Click for more on smart guides and content builds

Working with smart guides is a good starting point in general if you’re aligning elements that you generated outside of your slideware, like graphics from an external drawing program. It is very easy for individual components to become subtly misaligned once you paste them in, especially if you need to scale them, and correcting this can be difficult and frustrating.

The easiest way to benefit from smart guides in this scenario is to add a transparent rectangle whose center is a reasonable alignment point for the entire graphic and copy this along with each subset of elements that you want to build in at each step. This way, you can perfectly align multiple disjoint components of a given diagram at any size with smart guides because they will share a bounding box. Here’s an example of this technique in action, from this talk:

Footnotes

1. This can also be useful for code examples intended to provide the “feel” of a given programming idiom or technique, often by showing how accomplish a task that the audience is likely to be familiar with in a language, framework, or idiom that they aren’t.

2. This excerpt is the word count example from Apache Hadoop 2.

3. I’ve used this to show hash-based sketches, like the Bloom filter, and machine learning algorithms, like the online self-organizing map training example above.