Not Just a Hat Rack, Efficient Web Development

If you are working on a web-related website and/or blog, you’ll inevitably need to display code snippets on your pages. And when you do for the first time, you’ll have some questions:

• How do I show code snippets without the browser rendering typical tags?
• How should I show code inline, both semantically and stylistically?
• How should I show larger, block level code snippets?

Displaying Code without Rendering

Let’s say you want to display the HTML code for a hyperlink to your readers. Well if you just write:

<a href="http://somesite.com">somesite.com</a>

…it will display as:

somesite.com

In order to get your desired effect, you’ll have to replace the characters that the browser views as pertaining to HTML with their associated character codes or entities:

• < has to be <
• > has to be >
• " can be "
• & can be &

So going back to the link example above, typing:

<a href="http://somesite.com">somesite.com</a>

…will yield the desired result:

<a href="http://somesite.com">somesite.com</a>

This may seem like an unnecessary amount of work, and you’re right, it is. You can write your own script to replace the characters, you can use a WordPress plugin, or you can do what I do and use HTMLLizer.

Inline Code

The <code> tag is provided in the HTML standard as a phrase element that “Designates a fragment of computer code.” No specific style recommendation is given, but typically visual user agents will render text within the tag as a different font, typically a monospaced font like courier.

So displaying code inline is as easy as replacing the aforementioned special characters, and wrapping it in <code> tags. You can style it like any other HTML element, so feel free to change the color or font size if you want it to standout more.

Displaying Larger Blocks of Code

Using <code> tags works fine inline, but what if I want to display a multi-line code snippet? You’ve got a couple of decent options:

• Put the <code> tags inside of a <p> tag or other typical block-level element to give it the required spacing.
  • Pros: Works without any additional styling.
  • Cons: Would have to account for long lines of code somehow. Typical block-level tags do not preserve spacing and line breaks.
• Put <code> tags inside of a <pre> tag. <pre> indicates preformatted text, and is commonly used to display code.
  • Pros: Maintains spacing and breaks. Works without any additional styling.
  • Cons: Would have to account for long lines of code somehow.
• Put <code> tags inside of list items in an ordered list.
  • Pros: Line numbers account for long line issue. Breaks are maintained by making each line a separate list item. More flexibility in styling individual lines.
  • Cons: More code. Will need initial styling to work correctly. Does not preserve spacing. Copy and paste copies line numbers as well as text.
• Use a third-party code display tool and/or syntax highlighter like syntaxhighlighter.
  • Pros: Lots of out-of-the box functionality. Preserves line breaks and spacing for you. Syntax highlighting should add to the user experience.
  • Cons: Bloat! May or may not be semantically viable. Requires setup.

For the majority of users, third party syntax highlighters would more than likely offer the best experience given their ease of readability and additional functionality. However, reliance on Javascript, additional code output, and additional code to download isn’t worth the added functionality, and as such I’ll have to table using such a tool for the time being.

Using <pre> is probably the easiest method, because it requires the least amount of code and it preserves spacing and line breaks so you can just copy and paste into your pages. However, poor delineation between lines can definitely be an issue with longer lines of code, and severely hampers readability.

So despite the major issues (no preservation of spacing, copy and paste copies line numbers), for the time being I’ll be using the ordered list method of displaying code. I hope to revisit this solution in subsequent posts to see if I can eliminate some of my concerns, but for the time being I think it works pretty well:

<?php
echo 'hello world';
?>