Presenting code is one of the more difficult aspects of giving a programming presentation. Too little code can make it difficult to understand the concepts being explained. Too much code can be overwhelming, and can make your talk seem very dry.
There are a few tips around presenting code that can make it much easier for an audience to follow along while you describe code.
#Format For Readability
Requirements for streamed or recorded talks are different from presenting in person, but not all that different. Whereas before you needed to consider the person sitting at the back of the room trying to read your code on a projector, now you need to consider the person watching your video on YouTube on an iPad, or even their mobile phone!
The basics are:
- Make your text as large as possible.
- Use a clear typeface.
- Make it high contrast.
#Make Your Text as Large as Possible
Personally, I aim for 18pt (or above), but sometimes have to drop down to 14pt. I recommend not dropping lower than 14pt! If your presentation software automatically shrinks text when you have too much to fit, then you should turn this feature off. It makes it easy to put too much code in your slides, and leads to inconsistent text size between slides.
This obviously limits the amount of code you can display on a slide, especially how long your lines are. This is actually an advantage. The limitation will usually make your code slides better.
Using large text has a few advantages as well as the obvious one of making it easier for the audience to read your slides: It also means that slide screenshots can be more easily used as illustrations in a blog post, and they also work better when someone tweets their favourite slide from your talk!
#Use a Clear Typeface
A clear typeface for code has a medium weight and shouldn't be overly ornate.
These days, there are lots of typefaces to choose from! Don't use Courier New, even though it's available everywhere (and is often the default), because it's too light-weight to be readable.
MongoDB's official code font is Fira Mono. It is a great font. Its medium weight renders well at different sizes, and it is very clear. There's a version of Fira Mono, called Fira Code, which includes some modifications that make it better for code, but if you choose to use that, don't use ligatures. This feature combines multiple symbols, such as =>, into a single character like ⇒. It will confuse people who haven't seen it before.
#Make it High-Contrast
Ensure your color scheme has a high contrast between your foreground and background. That means a contrast in both light and dark, and also colours that are different enough from the background to be readable.
Ideally use black on white, or white on black, or highly contrasting levels of gray. Pygments' "bw" theme will highlight keywords in your code using bold and italic text, instead of color:
If you choose to have a color scheme for your syntax-highlighted code, ensure that it contrasts strongly with your chosen background. There are many tools, such as Palleton, that will help you find a color scheme with suitably contrasting colors.
#How to Format Your Code
There are a few tools that may make formatting your code easier!
If you use VS Code, copying your code and pasting into your presentation software should maintain the syntax highlighting you can see in VS Code! In PowerPoint, use "Paste Special" to insert your code with syntax highlighting. Remember to increase the size of the text, and possibly change the font, after you've pasted in the code:
1 MONGODB_URI = os.environ['MONGODB_URI'] 2 3 # Connect to your MongoDB cluster: 4 client = MongoClient(MONGODB_URI) 5 6 # List all the databases in the cluster: 7 for db_info in client.list_database_names(): 8 9 print(db_info)
If you prefer more of a command-line solution, the Python library pygments includes a command-line tool for formatting code, called pygmentize. You can pipe your code into pygmentize and it will produce syntax-highlighted output in a number of formats, including RTF and HTML. RTF works well on MacOS, allowing you to paste code from the command-line.
There are many color schemes available in the tool, or you can configure
your own. Consider using the
bw theme, which will use bold and
italic text instead of color to differentiate parts of your
Sadly, moncode doesn't yet work on Windows, and may not work on Linux. If that's something you'd like to see, please let me know on the moncode GitHub repo.
There's an online tool called Carbon. As well as syntax highlighting your code, it also puts a nice border around it, and optionally other decorations, such as the window controls you can see below:
Of all of these tools, Carbon is probably the easiest to use. Simply copy in your code, and then press the Export button to download an image to paste into your presentation.
Finally, you should seriously consider not using any syntax highlighting in your code slides. If your code examples are clear and concise, then it may not make it any easier to read the code. Without syntax highlighting, you're free to use a highlight color to highlight specific areas of the code you want to focus on, like this:
It is easy to underestimate the amount of time that an audience requires to understand the concepts in your code. They require enough time to:
- Understand what the code is supposed to do.
- Actually read the code.
- Understand how the code achieves its aims.
- Listen to what you're saying about the code!
And they can't necessarily do all of those things at the same time!
Your programming language may not be your audience's primary programming language, which means it may take more time to read and understand the code, and they may need some language-specific concepts explicitly explained to them. Unless it's important to the working of your code example, try to avoid unusual language idioms or particularly complex constructs. The audience won't understand how clever you are if they can't understand what your code does!
#Choose Your Examples Wisely
Here's a specific example of some Python code I once used in a presentation:
This is terrible example code! I had become so focussed on making the code as simple as possible that I made two glaring mistakes.
- It's not a concrete example. It's difficult to understand why I would write this code, so it's difficult to understand what it even does.
- Everything's called 'a'! I spent quite a while using sentences like "So we have defined a class called a, and I'm assigning it to a variable called a." It was a mess.
Learn from my mistakes. Use concrete examples if you can (because if there's a real-world use-case, it's easier to understand what the code does). Use sensible and easily spoken variable names. Don't use variable names that sound similar, like "i" and "aye," in a single slide.
Use as little code as possible to present your idea. Your code doesn't have to compile. It just has to illustrate what you're trying to teach.
Build up the code if possible, so people have time to understand the larger concepts. Use transitions to illustrate how code is building/changing. Otherwise, they need a moment to see the difference between slides. A nice technique is to build up the code a few lines at a time, with each slide highlighting the lines that have been added in that slide.
Step the audience through all the important points of your code, potentially fading out code that you're not immediately describing, so that it's still readable, but bringing what you're describing into the foreground.
It can often be useful to illustrate what the code does with a diagram, either before or after presenting the code itself.
One of the reasons people often like to see live coding (an inherently risky strategy for a speaker!) is that it slows down the presentation of code to the typing speed of the presenter.
Rather than giving a live demonstration during your final recording, record the interaction with the tool and play it back as part of the presentation. This approach reduces stress and prevents errors.
You can still present code in a "live coding" style, as if it is being typed as you speak, using a tool like asciinema, which allows you to record a console session and then play it back on a number of platforms. You can also simply do a screen recording of live coding in your favourite IDE and add it as a video into your slides.
The tips for presenting data are very similar to presenting code:
- Use the smallest possible example that will work.
- Use formatting/syntax highlighting to display structure.
- If the data is complex, build it up over a few slides.
- Try to present the structure of the data as well as some example content.
Often, a diagram will better illustrate your data structure than showing a big block of syntax-highlighted JSON, and using this alongside some example data can be a clear way of presenting the data you're working with.
#Create a Master Slide for Code
The official MongoDB template contains two master slides for code, which makes it very quick to create a new slide with the correct layout and formatting to display a block of code.
If you're using your own template, you can create your own "code" master slide. (Check the documentation for your presentation tool for specific instructions on editing master slides.) One big benefit of this approach is that if you decide you want to change the formatting of all your code slides, you can do it in the master slide. This will change all of the slides using that master in one go.
The advice in this post can be summarized in four points:
- Keep the amount of code to a minimum.
- Make the code as simple as possible.
- Format the code to make it clear and readable.
- Build up the concepts slowly so that the audience has time to understand.
If you can follow this advice, you'll give your audience the tools they need to understand the code you're presenting and they'll be with you on the wonderful journey of learning and discovery that you've planned.