Code screenshot best practices: how to share code people actually read

Quick answer: A good code screenshot makes one point, shows 5–20 lines no wider than about 80 characters, uses a large font with high-contrast colors, and is readable on a phone without zooming. Pair it with a caption that states the takeaway, alt text that contains the code, and a link to the source.

A code image has a few seconds to earn attention. In a social feed it competes with photos and videos; in a slide it competes with the speaker; in a blog post it competes with the reader's urge to skim. Most code screenshots lose for the same reasons: too much code, text that is too small, and a frame that is louder than the content.

This guide is a checklist for avoiding all three, with the reasoning behind each rule so you can decide when to break it.

Decide what the image is for before you paste anything

Every effective code image makes exactly one point. Before you start, finish this sentence: "The reader should notice…"

• …that the new API removes ten lines of boilerplate.
• …that the bug is an off-by-one on line 4.
• …that approach B is easier to read than approach A.

Once you know the point, you know what to cut. If you cannot finish the sentence, you probably want to link to a file or a gist instead. Images are for highlighting an idea; repositories are for storing code.

Show less code than you think

The most common mistake is pasting an entire function or file. A practical range is 5 to 20 lines.

• Under five lines, inline code in your post is often clearer than an image.
• Over twenty lines, the font has to shrink so far that the image is unreadable on a phone, where most social media is viewed.

Ways to trim a snippet without making it misleading:

• Drop imports unless the import is the news (a new package or module).
• Collapse irrelevant bodies into a comment: // …validation omitted.
• Shorten long identifiers when the domain does not matter to the point.
• Remove logging and defensive checks that distract — but say so if leaving them out could mislead someone copying the code.

Never trim code into something that would not compile or would behave differently without saying so. People retype code from images, and a broken example costs you credibility.

Keep lines short and the shape sensible

Line length decides the width of the image, and width decides how much a platform shrinks it. A 120-character line produces a wide strip that becomes tiny in a feed.

Aim for 60–80 characters per line:

// Before: one 118-character line
const result = await fetchUserProfile(userId, { includeOrders: true, includeAddresses: true, cache: "no-store" });

// After: easy to read at any size
const result = await fetchUserProfile(userId, {
  includeOrders: true,
  includeAddresses: true,
  cache: "no-store",
});

Images between square (1:1) and landscape (16:9) survive feed cropping best. Very tall images may be cropped in the preview; very wide ones become small.

Make the text readable on a phone

Test the image where it will be seen. Open the exported file on your phone, or make your browser window about 400 pixels wide, and try to read it. If you have to zoom, it has failed.

Fix it in this order:

1. Show fewer lines.
2. Shorten the lines.
3. Reduce the padding around the window.
4. Only then, reduce the font size.

Export at 2× resolution so text stays crisp on high-density screens and survives the recompression social platforms apply. A 700-pixel-wide frame exported at 2× becomes a 1,400-pixel image.

Choose contrast over style

Many popular themes give comments and punctuation deliberately low contrast. That is pleasant in an editor and invisible in a thumbnail. If your point lives in a comment, choose a theme where comments are clearly legible, or move the explanation into the caption.

The background behind the window should frame the code, not compete with it. Subtle, darker backdrops keep attention on the text; bright gradients suit announcements where the image itself is the brand moment. Our guide to the best fonts and themes for code screenshots goes deeper.

Direct the reader's eye

When one line matters more than the others, make that obvious:

• Add a pointer comment on the important line: // ← the fix.
• Use a diff for a change. Red and green lines with - and + markers say "before and after" instantly. The git diff image generator renders them clearly.
• Split comparisons into two images rather than cramming both versions into one.
• Use the window title for context. A filename such as auth.ts tells readers where they are without adding a line.

Write a caption that works on its own

Many people read your caption and never open the image; others see the image reshared without your caption. Each should stand alone.

A good caption states the takeaway in one sentence — "Array.prototype.at(-1) reads the last element without arr.length - 1" — and the image provides the evidence.

Always add alt text and a link to the source

Alt text replaces the image for screen-reader users and for anyone on a slow connection, and it makes your code copyable. On X you have up to 1,000 characters; on Mastodon, 1,500. That is usually enough for the whole snippet. See how to write alt text for code images for templates.

Then link to the real code — a repository, a gist or a documentation page. An image is a preview, not a deliverable.

Check for secrets one last time

Scan every line for API keys, tokens, internal hostnames, customer data and email addresses. Screenshots are copied, cached and indexed; deleting a post does not remove it from everyone's timeline. Our guide on how to redact secrets in screenshots lists where they usually hide.

Platform-by-platform recommendations

Platform	What works best
X, Bluesky, Mastodon	Under 15 lines, square or landscape, high-contrast dark theme, alt text containing the code
LinkedIn	A little more context is fine; explain the impact in the caption, not only the syntax
Slides	Fewer than 10 lines, very large font, theme matched to the slide background
Blog posts and docs	Real code blocks for anything readers copy; images for hero visuals and comparisons
Chat (Slack, Discord)	Copy the image to the clipboard and paste; include the code as text if someone needs to run it

The pre-publish checklist

1. The image makes one point I can state in a sentence.
2. It shows 5–20 lines, each under about 80 characters.
3. It is readable on a phone without zooming.
4. The important line is obvious at a glance.
5. The caption states the takeaway; the alt text contains the code.
6. There is a link to the real source.
7. There are no secrets, personal data or internal URLs.

When you are ready, paste your trimmed snippet into the code to image generator and check it against this list. If the number, not the code, is the story — a launch, a download count, a streak — the developer milestone card maker is a better fit.

Frequently asked questions

How many lines of code should a code screenshot have?

Between 5 and 20 lines is a good range. Fewer than five is often clearer as inline text; more than twenty forces the font so small that the image is hard to read on a phone.

What is the best size for a code image on social media?

Aim for a square to 16:9 landscape image exported at 2× resolution, with lines no longer than about 80 characters. That shape survives feed cropping and scaling on most platforms.

Should I use a dark or light theme for code screenshots?

Either works. Dark themes are popular in social feeds; light themes suit white documentation pages and print. Choose based on where the image will appear, and check that comments and punctuation remain readable.

Is it better to share code as an image or as text?

Use text whenever readers need to copy or run the code. Use an image when the goal is to highlight an idea or a change at a glance — and add alt text and a link to the source so the code is still accessible.