The Problems With Code Screenshots

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 almost always a better alternative.

I recommend:

  • Sharing raw text code, with syntax highlighting and formatting
  • Including a link to the source code online if you can

Problem Background

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:

  • They aren’t searchable
  • They point indirectly to the code
  • They aren’t accessible
  • I can’t mark them up
  • They force me to think about your custom environment

Let’s look at each.

Problem: Searchability

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.

Problem: Indirect Signal

Second, they point indirectly to the code.

Many times I’ve observed the following interaction:

  • Dev Alpha: “(Posts a screenshot of code). Here’s the function that’s breaking everything!”
  • Dev Bravo: “Where is that function located?”
  • Dev Alpha: “It’s in the users helper.”
  • Dev Bravo: “In the web app or the mobile app?”
  • Dev Alpha: “Web app.”
  • Dev Bravo: “Let me take a look. (Ten minutes pass). I can’t find it.”
  • Dev Alpha: “(Two minutes pass) Sorry, I meant the mobile app.”
  • Dev Bravo: “(Two minutes pass) I still can’t find it. The users helper?”
  • Dev Alpha: “(Two minutes pass) Sorry, I meant the customers helper.”

Et cetera. It’s not a direct path to the code.

Problem: Accessibility

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.

Problem: Edit-ability

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

Problem: Adds Irrelevant Information

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.

The Solution

What’s the solution? I try to do one or both of the following:

  • Share raw text code, with syntax highlighting and formatting
  • Include a link to the source code online if I can

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.