How to present code in my text document?

Question

I'm writing some articles, mainly in blogs or small, approximately 1 paper long, printed articles.

Now this text contains some code. Most often it is not a code block but just a method name, a variable name or a class name.

For that I have some questions:

• Is it a good idea to write this part of the text in another font?
• If I chose to use another font, which one can I take to make it optimally readable?
• If I should not chose another font, is there any other way to highlight/differentiate this part of the text? Or shouldn't I do it at all?

Answer 1

I think it's very important to differentiate code text from normal text as it is very much another language, and it's standard proceedure to differentiate text written in other languages--usually using italics.

A good example of sites using code differentiation is the Stack Exchange family, as you may have noticed it's very important to differentiate code when asking programming questions, in no small part because the different, usually monospaced font, makes code easier to read.

Here's a good list of "Good programming fonts", monospaced fonts are usually the default for readability's sake as they clearly separate letters so you never have to wonder if that's an rn or an m. Clarity of l, I and 1 (l, I and 1) are very important as well, as you can see l and I are virtually identical using UX.SE's default font, but clearly identifiable in the nice monospaced fonts they use for code.

While I do recommend using a different font, using other methods of highlighting can be helpful too; if you have a programmer audience they will likely appreciate some consistant variable name/method name/ect highlighting similar to popular IDEs and editors like Notepad++. I believe Stack Overflow attempts to do this.

Answer 2

Yes, that is a good idea, as it will improve the readability of the document. StackExchange actually does this very well in my opinion. Notice that the background color is also slightly changed. This signals to the user that the text below is in a different context. You can also include a dashed outline if changing the background color is not an option.

class example
{
    function show()
    {
        echo "Showing Example";
    }
}

I would personally recommend any of the following:

• Andale Mono (MS)
• Courier New (MS)
• Lucida Console (MS)
• Bitstream Vera Sans Mono (Gnome)

These fonts have character proportions that are more natural than others, and are very easy to read in general. Unlike other fonts, such as Microsoft's Consolas, they read well regardless of the user's anti-aliasing or clear-type settings.

For use on your blog, just wrap the text in a <pre> tag, and style it through CSS. For use in print, you may need to license use of the font. The MS fonts may be licensed through Ascender Fonts, and the last one is free from the Gnome project.

Answer 3

It can be useful to delineate the code - even when it's just variable name - by using another font as it can distinguish between an "instance of a class" and class called instance. This will be especially true if your names are sensible class/method/property names (like car, person, height) which could appear in the text anyway. This acts as reinforcement that you are talking about your code rather than the things that they represent.

Given you are including code, I'm going to assume that you are writing for a technical audience, in that case Courier New or Consolas are probably good choices for the font. They are readable and what the reader will be familiar with.