Scott Hanselman

If you've got a programming blog, chances are you'll want to post some code snippets. Posting code sounds easy but it's surprisingly tricky if you consider all the ways that people will be reading your blog. There's a number of ways. Here's a few and their pros and cons.

Copy Paste from your IDE (like Visual Studio, for example)

If I copy paste directly from VS into my editor of choice, Windows Live Writer, I'll get a <pre> section.

using System;
 
namespace WindowsGame1
{
#if WINDOWS || XBOX
    static class Program
    {
        /// <summary>
        /// The main entry point for the application.
        /// </summary>
        static void Main(string[] args)
        {
            using (Game1 game = new Game1())
            {
                game.Run();
            }
        }
    }
#endif
}

Pros:

• It's just text.
• Looks the same everywhere.
• Code is in a pre and you can apply css rules to pre's if you like.

Cons:

• It's just text.
• Looks the same everywhere.

I can also go to the Visual Studio Gallery and get the Copy As HTML Extension from inside the "Productivity Power Tools." When someone names something "Productivity Power Tools" but doesn't include it out of the box that means they are "things that aren't totally tested and that would blow your mind if we did include them in the box so just get them and be happy but we are sorry we didn't ship them straight away."

Once this extension is plugged in, when I Ctrl-C some text, VS adds not just plain text to the clipboard but also rich HTML and what-not.

using System;
 
namespace WindowsGame1
{
#if WINDOWS || XBOX
    static class Program
    {
        /// <summary>
        /// The main entry point for the application.
        /// </summary>
        static void Main(string[] args)
        {
            using (Game1 game = new Game1())
            {
                game.Run();
            }
        }
    }
#endif
}

This looks lovely, but it includes a pile of <spans> and now my code is a bunch of marked up HTML, rather than a block of code.

Pros:

• Looks the same everywhere, RSS or on your site. Consistent.
• Will always look like this, no need to change anything.

Cons:

• Inline styles and colors. Ick.
• Span-itis.
• Stores the formatting in your blog system directly (in the DB, etc)
• Will always look like this, you can't change anything.

Using PreCode and SyntaxHighlighter

PreCode is Anthony Bouch's Windows Live Writer plugin. SyntaxHighlighter is Alex Gorbatchev's JavaScript (that's client-side) syntax highlighter. SyntaxHighlighter highlights your code locally using <pre> blogs that are marked for specific languages. You include "brushes" for just the langugaes you care about. This is the combination that I currently use.

SyntaxHighlighter is definitely the client-side highlighter of choice, but there are others you might also check out including:

• Chili Highlighter - Hosted on Google Code
• Google Code Prettify - This is the code highlighter that Google themselves use on Google Code. It doesn't require you to specify the language. It works on most C-style languages, works iffy on Ruby, PHP and VB, and needs extensions for LISP and F# and others.

NOTE: Make sure whatever one you pick that you're cool with the OSS license for your library of choice.

From within Live Writer you click "Insert PreCode Snippet" and paste your snippet in. It has a number of nice options. I use HTML encode and "replace line endings with <br/> which is required for use in DasBlog for historical reasons. It also has a number of SyntaxHighlighter specific options for doing line-highlights or turning the toolbar on and off.

This creates output like this. Here's the trick, though. If you are reading this post via RSS, you're seeing just plain text. You need to visit this post on my site directly in order to see pretty fonts and colors because the JavaScript isn't firing in your RSS Reader.

It's created a <pre> that looks like this <pre class="brush: csharp; auto-links: false;"> and the JavaScript comes around later and processes it in the browser.

using System;

namespace WindowsGame1
{
#if WINDOWS || XBOX
    static class Program
    {
        /// <summary>
        /// The main entry point for the application.
        /// </summary>
        static void Main(string[] args)
        {
            using (Game1 game = new Game1())
            {
                game.Run();
            }
        }
    }
#endif
}

Pros:

• Having code stored in a pre means there's no formatting stored in your blog system.
• Looks great in any browser with JavaScript
• You can choose themes and change the look and feel of your code whatever
• You also get nice printing support, toolbars, line highlighting, etc.

Cons:

• RSS readers effectively lose out and see just text.
  • NOTE: There really is no "good" solution for RSS viewers unless your blog engine's RSS Feed Generator does the processing on the server-side for code blocks and sends <span>itis when the feed is requested.
• Once you've inserted code in WLW with PreCode, you can't easily edit the code. I usually edit it outside and paste again.

Using Code Formatter Plugin for Windows by Steve Dunn

Another Windows Live Writer plugin is Steve Dunn's Code Formatter. It has a few features that differ from PreCode, and a few quirks (as of the current version). It supports not just Syntax Highlighter style <pre>'s for code but also <span>itis inline styles using ActiPro's SyntaxHighlighter.

 1 using System;
 2 
 3 namespace WindowsGame1
 4 {
 5 #if WINDOWS || XBOX
 6     static class Program
 7     {
 8         /// <summary>
 9         /// The main entry point for the application.
10         /// </summary>
11         static void Main(string[] args)
12         {
13             using (Game1 game = new Game1())
14             {
15                 game.Run();
16             }
17         }
18     }
19 #endif
20 }

You can also insert code as images, which people do, so I mention it here, but I think is rude to blind folks, and not useful as GoogleBing can't see it. Don't do this. You're a bad person.

Pros:

• Supports WLW's "Smart Content Editing" so you can edit your code after you insert it.
• When using ActiPro
  • Looks the same everywhere, RSS or on your site.
  • Will always look like this, no need to change anything.
• When using SyntaxHighlighter
  • Looks great when users visit your site
• Supports images (if you're into that kind of thing and you are Satan)

Cons:

• When using ActiPro
  • Intense Span-itis and embedded colors.
  • Inline styles and colors. Ick.
  • Stores the formatting in your blog system directly (in the DB, etc)
• RSS readers effectively lose out and see just text.
• The plugin inserts unneeded (IMHO) inline styles like width and height.
• Supports images (if you're NOT into that kind of thing or you're blind.)

Hosting your Code elsewhere like GitHub

GitHub is a social code hosting and sharing site, and Gist is a part of their site where you can easily share code without logging in. You can create private or public Gists, or you can create your own GitHub login and keep the source you host on your blog in one place.

You can share your code by using embedded JavaScript like this: <script src="http://gist.github.com/516380.js?file=Hanselman%20Sample%201"></script>. You don't get too much control over the look and feel of it, but it "just works." 

using System;

namespace WindowsGame1
{
#if WINDOWS || XBOX
    static class Program
    {
        /// <summary>
        /// The main entry point for the application.
        /// </summary>
        static void Main(string[] args)
        {
            using (Game1 game = new Game1())
            {
                game.Run();
            }
        }
    }
#endif
}

Pros:

• You can store all your code in an external service, just like you might store all your pictures at Flickr.
• All your code is in once place.
• Dead simple.

Cons:

• You're no longer storing your code with your blog posts. You're storing a JavaScript link.
• You need Javascript running within your RSS reader for the code to show up. Most won't do this for security reasons. Otherwise, you'll see nothing.
• You can't control it. It's alive!

Conclusion

As with all religious arguments, I don't care who you choose to go with, just that you pick one and be excited about it, and that you know the pros and cons. You can certainly switch back and forth if you like, but I personally believe there's something to be said for consistency, so pick something you can live with for a few years, or your life on earth. ;)

Currently, I'm using PreCode with SyntaxHighlighter until a better solution comes along. Did I miss any good options?

About Scott

Scott Hanselman is a former professor, former Chief Architect in finance, now speaker, consultant, father, diabetic, and Microsoft employee. He is a failed stand-up comic, a cornrower, and a book author.

About   Newsletter

Hosting By