Jake Worth

The Limitations of Code Screenshots

Published: April 19, 2022 2 min read

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, and there’s a better way.

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— 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.

First, screenshots aren’t searchable. Yes, image search technology is advancing, and someday every screenshot will be translated to 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 to find, and it hurts us all later by hiding your question and maybe the answer.

Secondly, screenshots aren’t accessible. Screen readers were built to read text, not images. Even with a caption or accessibility attribute, bandwidth is lost. You’re hiding your question from a large percentage of people. That is both unnecessarily exclusive and counter to your interests.

Third, I can’t mark up a screenshot. Let’s say I spot the line in your stacktrace screenshot that explains the problem. Now what? I’m taking my own screenshot, marking it up with Preview or CleanShot, and sending it back to you. That’s asking a lot of a busy person.

Fourth, screenshots force me to enter your custom 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 Alternative

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

Yes, some fading platforms have limited ability to show code. Perhaps they don’t support the syntax you’re using. Try! If it’s unacceptable, post the code somewhere pro like a Github Gist. There you can satisfy that instinct to overshare by dumping as much stack trace as you want. I can respond with highlighted lines or a PR. 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.

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

✉️ Get better at programming by learning with me. Subscribe to Jake Worth's Newsletter for bi-weekly ideas, creations, and curated resources from across the world of programming. Join me today!

Blog of Jake Worth, software engineer in Maine.

© 2022 Jake Worth.