I have read from blogs and heard from several developers that dark theme is preferred over light themes. I also like the darker backgrounds with white-ish text when reading/writing code (or this article in Code). A lot of the API documentation containing code examples use dark background. The whole documentation is often not dark, but the code parts are. That can’t be a coincidense. Of course there are exceptions like the current Stripe API docs, which is by default dark, but has a switch to go for light theme. In the light theme code blocks are with darker background as expected. The question is not dark-light but also about contrast. This subject started to interest me today.
I just happened to stumble upon a research paper which had an interesting research question: “Does displaying code in dark-on-light or light-on-dark text colour themes yield an advantage in code readability?” (“The Impact of Colour Themes on Code Readability”). Code readability can be described as the ease of which a person reading some program source code is able to parse and understand its function. The research interestingly found no significant difference between the themes. The participants of the test did not perform better, be more accurate or faster with darker theme.
Most of the research exists on how light (dark text on light backgrounds) versus dark (light text on dark backgrounds) themes affect reading text. Furthermore the research is focused on web pages, not source code. Verbose text is faster and easier to read on light backgrounds. In addition the research is mostly based on eye-tracking method. Thus the amount of persons in tests is normally low. For example in the above mentioned research there was 10 participants. Thus the reliability of the results is always a question mark although the results do give us hints.
Back to practical approach. API documentation at best is both - it’s a combination of verbose text and code examples or snippets. Thus having the verbose text in light background is not a surprise in various API documentations.
What about the code examples then? Great API documentation for example contains lots of good working code examples. This a bit off the topic (power of the dark side), but closely related to it anyway.
The effect of syntax highlighting has been studied and key finding was that syntax highlighting improved code comprehension by reducing task completion time and context switches (“The impact of syntax colouring on program comprehension”). The magnitude of this effect decreases as programming experience increase. Benefits of highlighting was confirmed by couple of developers online. The dark theme is perceived to work better with syntax highlighting.
Dark room - dark editor…or learned habit
The surrounding conditions occasionally affect the preferred theme as it was stated by one developer when asked “Can you developers tell me why you like dark theme in coding?” The developer above added that the preference might also have some background in old 80’s line editors so it could be partially learned habit as well.
Regardless of the reference to 80’s this seems logical since according to research dark themes can reduce eye strain in low-light conditions (night-time or dimmer workspaces). The strain was also mentioned by another developer.
And now the stripe’s API docs theme switching feature introduced in the beginning makes even more sense. Bright for the office, dark for the dungeons and dragons of coding (Sarcasm again). Seriously speaking the bright version works better in bright conditions since dark theme washes out the text.
It is also claimed that dark theme is less power consumption option. That might depend of the screen too and not all screens are able to take advantage of it.
- Dark themes can reduce eye strain in low-light conditions (night-time or dimmer workspaces). And we all know that all code is written in basements with only light coming from the screen (sarcasm).
- High contrast between text and background reduces eye strain.
- Applications that require syntax highlighting (like programming) can be easier to see with light-on-dark themes.
- Dark themes can put more strain on your eyes in high-light conditions, since it washes out the text. For this purpose I think the idea of theme switching in API docs might be a good idea.
- 100% contrast (white text on a black background) is typically harder to read and may cause more eye strain.
- Applications that require reading long passages of text will typically be harder to read in a light-on-dark theme. Thus for example at the Platform of Trust API Docs verbose descriptions in the middle are in light background (not white).
So does the dark side have power? Obviously yes in some situations, but not all. In API Docs the optimal solution probably uses both as it was discussed previously. Code examples with syntax highlighting in dark (not black) background and verbose explanations on close to white background. The dark side might not prevail always as we’ve seen in Star Wars too. It sounds like the preference of dark themes is a combination of two factors. Firstly, it has some benefits for example while reading pure highlighted code. Secondly, it’s learned habit from the past. I’m tempted to add third one: it’s just different and looks cool, but no. That can not be….
Despite of the fact that dark theme is not like 90% better in every case than bright white-ish, I’ll stick with the dark backgrounds in code related and read scientific articles from white-ish background. It just feels right and better. And yes, I’m also one of the 80’s kids who started the journey towards code by fiddling with Commodore64.
Some more to read from 100 Days DX
- #85 - Great Developer eXperience requires fluent internal workflow
- #84 - Theory of Economics of Developer eXperience
- #83 - The Space of API Design Decisions is missing
- #82 - Purpose of API Evaluation Framework
- #81 - Should We Move to Stack Overflow?
- #80 - Four data driven ideas for improving API documentation
While you are here...
Check out Platform of Trust in which I've worked to enable best possible developer experience!