Published: April 19, 2022 • Updated: March 20, 2023 • 3 min read
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 always a better alternative!
Why do people post screenshots? My guess is to be helpful. They’re stuck, or they think you’re stuck and want to provide the maximum amount of information. What could be higher bandwidth than a picture? That instinct of over-communicating your predicament is great.
But screenshots have these deal-breaking limitations:
Let’s look at each.
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.
Second, they point indirectly to the code.
Many times I’ve observed the following interaction:
Et cetera. It’s not a direct path to the code.
Third, screenshots aren’t accessible.
Screen readers were built to read text, not images. Even with a caption or accessibility attribute, fidelity is lost. You’re hiding your question from a group of people. That is both pointlessly exclusive and counter to your interests.
Fourth, I can’t easily edit a screenshot.
Let’s say I spot the line in your stack trace screenshot that explains the problem. Great! Now what? I’m taking another screenshot, marking it up somehow, and sending it back to you. Day in and day out, that busywork adds up.
What if your function just needs one or two small changes? If you pasted raw code, I can copy it, make my changes in a my text editor with a test, and post the corrected function that I am certain works someplace for you to copy. This is so much more direct than “change the array at the top of the component to an array of arrays.”
Fifth, screenshots force me to think about your problem through the lens of your custom development environment, which is generally irrelevant.
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.
What’s the solution? I try to do one or both of the following:
For sharing raw text: 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 beautiful, well-presented screenshots to teach, and I don’t mean to criticize that workflow. It still suffers from the limitations above, but I see the value of presenting ideas this way.
Links are great, too! I use a Vim plugin called fugitive.vim lets me open a line of source code from Vim in the browser, or copy it as a link. Posting code this way clarifies what lines of code I’m talking about.
Post your code, not a screenshot, and let’s do this.
What are your thoughts on this? Let me know!
Join 100+ engineers who subscribe for advice, commentary, and technical deep-dives into the world of software.