Jake Worth

Jake Worth

The Problem With Code Screenshots

Published: April 19, 2022 • Updated: December 05, 2022 2 min read

  • debugging

When I’m helping someone debug and they share a screenshot of code, I know that helping them just got harder.

code screenshot
Trouble ahead.

A common anti-pattern on sites where code is discussed, such as Slack, Stack Overflow, Github Issues, etc., is to post a screenshot of code when asking for help. This technique has many problems.

Why do people post screenshots? My guess is to be helpful. They’re stuck and they’re thinking: “How can I provide the maximum information?” A picture tells a thousand words! That instinct of over-communicating your predicament is great.

But screenshots have some deal-breaking limitations:

  • They aren’t searchable
  • They aren’t accessible
  • I can’t mark them up
  • They force me to think in your custom environment

Let me address each of these.

The Problems

First, screenshots aren’t searchable. Yes, image search technology is advancing, and someday every screenshot will be translated into text and rapidly indexed. We aren’t there yet. Screenshots don’t help your question become discoverable. That hurts you now by making your problem harder for someone to find, and it hurts us all later by hiding your question and maybe the correct answer.

Secondly, screenshots aren’t accessible. Screen readers were built to read text, not images. Even with a caption or accessibility attribute, some information is lost. You’re hiding your question from a group of people. That is both pointlessly exclusive and counter to your interests as person who needs help.

Third, I can’t mark up a screenshot. Let’s say I spot the line in your stack trace screenshot that explains the problem. Great! Now what? I’m taking my own screenshot, marking it up somehow, and sending it back to you. That’s a lot of busy work.

Fourth, screenshots force me to think about your problem through the lens of your custom development environment. Everybody’s programming setup is unique, and I want to be thinking about your problem, not your text editor color scheme or anything else about your personal computer.

The Solution

So, what’s the alternative? Share raw text code, with syntax highlighting and formatting.

Yes, some fading platforms have limited ability to show code samples. Perhaps they don’t support the syntax you’re using. Try! If it’s unacceptable, post the code somewhere built for it, like a Github Gist. There you can satisfy that instinct to overshare by dumping as much of the stack trace as you want. I can respond with highlighted lines or a pull request. We’ll get to a solution much faster.

Some teachers use screenshots to teach, and I don’t mean to criticize that workflow. Teaching via curated screenshots of your Kitty Terminal with Patreon-supported Dracula Theme— rock on! It still suffers from the limitations above, but I see the value of presenting ideas this way.

Post your code, not a screenshot, and let’s do this.

Get better at programming by learning with me. Subscribe to my newsletter for weekly ideas, creations, and curated resources from across the world of programming. Join me today!