Formatting code in blogs


In a comment, Steve asks how I format code in my blog.  Here’s the answer:



  1. Write the code in Visual Studio.  Include correct references, ‘using’ directives, helper classes, fields, etc.  Make sure the code builds.  (I really should use NUnit to make sure it works.)  It’s amazing how much sample code out there is plain broken.  Not just in blogs, but even in expensive books.


  2. Because I’m using Whidbey, I get nice colorization of types.  (You see them showing in Bold Navy.)  I love this feature.


  3. Even though the blogging site I’m using lets me write in a WYSIWIG editor on a web page, I usually write the blog in Word.  For some reason, it’s really a pain to get good formatting in an HTML WYSIWIG editor.  It inserts blank space where I don’t want it, forgets my font settings, etc.  When I paste in code, it loses indenting & font settings. 


  4. I copy code from VS & paste it in Word.  VS fills the clipboard with (at least) two formats: text and RTF.  Word prefers the RTF, so its gets my formatting.  I think that RTF pasting into the HTML editor is extra-broken.


  5. I select the pasted code & click the Outside Border toolbar button to draw a nice box around the code.

I also have a predefined style called “code” that I use when there’s a bit of code in the middle of a sentence.  There’s a typesetting style where langue étrangère should be italicized.  I’m doing the same thing by putting keywords & indentifiers in fixed width, I guess.


 

Comments (12)

  1. RB says:

    I’ve written a HTML WYSIWYG editor and Word is it’s second worst enemy (worst is Excel). The "HTML" generated by Word is unbelievably bad. Around 90% of the code is dedicated to trying to clean up Word HTML so that it can be displayed correctly in our (hopefully valid) XHTML websites.

    One day when you’re in Word, save your document as HTML and veiw it in notepad. The amount of bad HTML in there will amaze you.

    So rather than stating that the RTF pasting is extra-broken, it would be more correct to say that the coders didn’t have an extra two months to spend writing code to specifically clean up the crap from Word.

  2. Robert says:

    What’s wrong with simply putting your code inside PRE and/or CODE tags? Then you don’t end up with all those bizarre MS Office xml tags that take up so much space.

  3. jaybaz_MS says:

    Robert: what smart tags are you talking about? I don’t think I’ve seen them.

  4. You may want to read Phil Ringnaldas comments on clean code.

    http://philringnalda.com/blog/2004/04/html_is_code.php

  5. James says:

    this page doesn’t even validate…

    http://validator.w3.org/check?uri=http://blogs.msdn.com/jaybaz_ms/archive/2004/03/30/103505.aspx

    so you’re code isn’t that clean!

  6. jaybaz [MS] says:

    James: Yeah, you’re not the first person to tell me. Word generates nasty looking HTML that looks great when rendered. If you have any suggestions on how I can format my blog to look good *AND* have attractive HTML, let me know.

  7. <p>
    <a href="http://blogs.msdn.com/brada/archive/2004/10/05/238427.aspx">Brad Abrams</a>,
    <a href="http://blogs.msdn.com/jaybaz_ms/archive/2004/03/30/103505.aspx">Jay Bazuzi</a>,
    <a href="http://weblogs.asp.net/rosherove/archive/2004/02/05/67957.aspx">Roy Osherove</a>,
    and what seems like the majority of .NET bloggers use Word, Word macros, or Visual Studio macros that use Word
    in some way to format their code. A few use
    <a href="http://www.manoli.net/">Jean-Claude Manoli</a>’s
    <a href="http://www.manoli.net/csharpformat/">CSharpFormat</a&gt;
    tool. Each solution has drawbacks (opening Word, opening another browser window, copying and pasting, extra steps,
    terrible HTML, etc) and formatting code is still painful. So…
    </p>
    <p>
    I’ve written a simple Visual Studio add-in that allows you to copy source as HTML suitable for pasting into blogs…
    </p>

  8. Brad Abrams, Jay Bazuzi, Roy Osherove, and what seems like the majority of .NET bloggers use Word, Word macros, or Visual Studio macros that use Word in some way to format their code. A few use Jean-Claude Manoli’s CSharpFormat…

  9. Peter Gray left a comment that I can reduce the a part of the spring example even further, from this:public long getNewPrimaryKey(String sequenceName) { JdbcTemplate jdbcTemp = new JdbcTemplate(dataSource); long seqKey = jdbcTemp.queryForLong("select "+sequenceName+".nextval from dual"); return seqKey; } to this:public long getNewPrimaryKey(String sequenceName) { OracleSequenceMaxValueIncrementer osmvi = new OracleSequenceMaxValueIncrementer(dataSource,sequenceName); return osmvi.nextLongValue(); } And you swap the constructor for a call to the bean factory to get an instance of the bean if you have it configured in your spring.xml…

  10. Brad Abrams, Jay Bazuzi, Roy Osherove, and what seems like the majority of .NET bloggers use Word, Word macros, or Visual Studio macros that use Word in some way to format their code. A few use Jean-Claude Manoli’s CSharpFormat…