How to format code blocks for narrow screens

You’ll need to break with programming conventions and language style guides to make blocks of code fit on mobile. Making preformatted code blocks fit on narrow screens is an under-appropriated art form.

Code is usually presented in wide preformatted blocks which are set in a fixed-width font with a significant amount of indentation whitespace. These blocks don’t always fit within the available space in page layouts on PCs. They often require horizontal scrolling or are scaled down to unreadable font sizes for mobile.

So what can you do about your code blocks to make the experience better for mobile readers?

In this article, I’ll focus on mobile screens and ignore ultra-narrow screens like smartwatches. Pixel sizes throughout this article are screen-resolution-independent and use the CSS measurement definition of a pixel (96 pixels equals 1 inch) rather than using physical device pixels.

Less than half the traditional character per line (cpl) limit

For historical reasons dating back to code written on punch cards in the 1920s and carried on through terminal-screens from the 70s; programming style guides and editors set the line-length to 80-characters per line (cpl) or less. You’ll find this enforced today in the Style Guide for Python Code (PEP 8), the Ruby Style Guide, and many others.

However, you’re not going to fit up to 80-characters of a fixed-width font face onto a mobile screen and maintain a readable font size. You can at most fit 32 characters at a comfortable 18px font size on a 360 px wide display (including a 10 px margin at either side). This is one of the most common mobile resolutions and also the smallest one.

You can fit in 64 characters if you ask your readers to flip their phones horizontally. They’ll surely resent you for asking and interrupting their reading. There are still many phones on the market, even new ones, that have square displays.

You can make a fluid preformatted code block that reflows to fit within the character limits for narrow (mobile portrait), medium (mobile landscape/tablet), and large displays (PCs). You likely have to do this yourself as there are no automated tools for the job.

At this point, advanced CSS-stylists may be thinking of CSS rulesets like white-space: pre-wrap; word-break: break-word;. However, this method won’t handle indentation levels and would break lines in inopportune places.

Instead, you’d need to invest the time to manually wrap segments of code at opportune places in a display: inline-block; elements. Your stylesheet (probably aided by JavaScript) would need to apply proper levels of indentation to wrapped lines. This would be a time-consuming process.

Horizontal scrolling

You’ll want to avoid relying on horizontal scrolling to present your code blocks. Horizontal scrolling hides potential information by pushing it off on an unexpected axis. The reader expects to find reveal more content by scrolling the document vertically. Many browsers also hide scrollbars by default, so the reader doesn’t have a visual hint that there will be more content off to the side.

Long line-lengths with horizontal scrolling makes it harder to find your place on the next line of text (the “return sweep”).

Horizontal scrolling can be unavoidable in situations where unbreakable long strings are expected (e.g. URLs, file paths, or long function names). Make sure you include hints in your design so readers will notice that there’s more content off to the side.

Indentation

Always indent using two space characters instead of a tab character. A tab-character is eight spaces by default. This is valuable space that you can’t afford to waste on a tight characters-per-line budget.

Disregard your preferred indentation style or the conventions of the language. The only times you want to use a tab character if it’s a significant character in your code block.

There is some hope for you still if you insist on using tab characters rather than spaces. The CSS property tab-size can be used to redefine the length. E.g. tab-size: 2; to make a tab character two spaces wide. However, browser support is limited.

Conclusions

You either need to spread your resources thin and format three separate code blocks for mobile, tablets, and large screens. Alternatively, you cam choose to focus on the mobile web.

You’re limited to 32 cpl and conservative use of indentation. Also, make sure you test both your design and your content on mobile.