Inline Code Listings

Jul 16, 2021#writing

Code listings are generally presented as a few lines of code printed inline within larger bits of documentation prose, most often carved out in a small “code box” area. This code is generally authored right along side the prose by a writer, in their favorite text editor.

These inline code listings are written once and meant to be consumed in one particular manner. While these bits of code are incredibly helpful while reading the documentation — often this is the best sort of documentation — there are downsides, too.

Code listings tend to go stale. Code listings, once put into the documentation, tend to be treated as regular text. The code isn’t built regularly, and may not be revisited by the author for a long period of time. Over time, changes to the programming language or APIs can easily make code listings go stale and stop compiling successfully.

Code listings don’t get good editor support. As most code listings are typed into an editor focused on writing prose, the author misses out on the coding features typically available in a code editor or IDE. Missing inline error checking and syntax highlighting means it is much more likely the code sample will have an error.

Code listings tend to be more like pseudocode. This happens because the author knows they aren’t actually building running code, and all the explanation for the code happens in the surrounding prose. This results in code that is much less useful for the reader to copy into their own projects.