Jake Worth

On 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 antipattern 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. 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— great.

But screenshots have some deal-breaking limitations: they aren’t searchable; they aren’t accessible; I can’t mark them up, and they force me into your custom environment.

First, screenshots aren’t searchable. Yes, image search technology is advancing, and someday every screenshot will be translated to text and indexed in every search engine. That isn’t happening today. 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 the question and maybe the answer.

Secondly, screenshots aren’t accessible. Screen readers can read text, but I imagine they struggle with screenshots for the reasons above. Even with a caption or accessibility attribute, bandwidth is curtailed. You’re hiding your question from a large percentage of people, a decision both 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.

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 relative numbering scheme or bright red ESLint warnings.

So, what’s the better way? Share text code, with 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, and we’ll get to a solution much faster.

Some teachers use screenshots to teach, and I don’t mean to knock that workflow. Teaching via well-edited 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.