The Problems With Code Screenshots

Screenshots of code are common in developer communication, but they come with real drawbacks. Here’s why I try to avoid them.

Screenshots happen. People are often under time pressure, on phones, or unfamiliar with best practices. Some people feel more confident communicating with images. I’m here to offer solutions, not shame.

Problem Background

Why does one post screenshots? To be helpful. You’re stuck and want to provide high-bandwidth information. What could be higher bandwidth than a picture? I appreciate that helpful spirit.

But code screenshots have limitations:

  • They aren’t searchable
  • They’re indirect
  • They aren’t accessible
  • I can’t mark them up

Let’s look at each.

Problem: Searchability

Screenshots aren’t searchable.

Yes, image search technology is advancing, but screenshots don’t help your question become discoverable today. That hurts you now by making your problem harder for a helper to find, and all of us later by hiding your question from someone in the same predicament.

Problem: Indirect Signal

Screenshots are indirect.

Here’s a common interaction:

  • Dev Alpha: “(Posts a screenshot of code). Here’s the function that’s breaking everything.”
  • Dev Bravo: “Where is that?”
  • Dev Alpha: “The users helper.”
  • Dev Bravo: “Let me look! (Ten minutes pass). I can’t find it.”

When somebody shares a stack trace with me, something I often do is paste a line or two into a search engine or LLM. With a screenshot, I have to use an OCR (Optical Character Recognition) tool to get that line, or hand-type it. It’s an error vector.

Problem: Accessibility

Screenshots aren’t accessible.

Screen readers were built to read text, not images. Even with a caption or alt text, information is lost. Cognitive load, dyslexia, vision impairments, and language translation all work better with words.

Including people is kind, and in your interest as a person who needs help.

Problem: Edit-ability

I can’t easily edit a screenshot.

Let’s say I spot the line in your screenshot that explains the problem. Now what? I’m taking my own screenshot, marking it up, and sending it back to you. That gets messy.

What if your code only needs one or two small changes? If you pasted raw code, I can copy it, make my changes, and post the corrected code someplace for you to copy. Wouldn’t that be nice?

The Solution

What is the solution? I try to do one or two of the following:

  • Share a downloadable file (logs)
  • Share raw text code, with syntax highlighting and formatting
  • Include a link to the source code online

Some teachers use well-edited screenshots to teach, and that’s cool. It suffers from the limitations described, but I see the value of it.

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