It occurred to me the other day that there’s information out there about the technical aspects of writing XML doc comments in .NET code (i.e., the markup tags) but there’s nothing out there about what you should put in that markup.  While not every developer is also a technical writer or novelist, sometimes all the users of your code have to go on is the documentation you generate, so it’s important to write it well.

And, no, you can’t just defer your users to Reflector.  You’d actually be amazed at how many people don’t even know what Reflector is.

TL;DR - THE GOLDEN RULES OF DOCUMENTATION There’s a lot here. If you don’t take anything else away, please at least take these two things:

• Write like it’s MSDN. After you write the documentation, read it back to yourself, maybe even out loud. Does it sound like something you’d read from MSDN? How’s the grammar? They have smart people writing docs over there - learn from them the same as you “View Source” to learn good HTML.
• Write like the reader doesn’t have the source code. Write the doc, then collapse all the method definitions so all you see is XML doc. Go get a coffee. Come back. Now read the documentation. Does it tell you everything you will need to know to work with the function? Pretend the reader doesn’t have Reflector (you’d be surprised, lots don’t).

Given those two rules, here are some tips on writing better XML doc comments:

1. Think about what you’d like to see and write that.  I intentionally made this the number one rule because it’s the most important.  When you’re writing your documentation, step outside yourself for a minute and think, “If I was handed just this assembly and a help doc, and I didn’t have access to Reflector or anything like that, what sort of documentation would help me to understand how to use this code?”  Remember:
   • Your users won’t necessarily have the source to refer to, and even if they do, you shouldn’t force them to resort to that.
   • Not everyone knows everything you know about the code.
   • The flow of control may not actually be as obvious as you think.
2. Learn the markup.  If you only know about the <summary/> tag that gets put in when you hit /// (or ''', for you VB people), you don’t know XML doc comments.  MSDN has the reference for the base tag set but there is a good reference here that includes a set of fairly widely accepted extensions. There’s a lot more to comments than the summary.
3. Keep the <summary/> short.  The content in the <summary/> and <param/> tags shows up in Intellisense in the Visual Studio IDE.  Don’t write a novel there - one sentence, maybe two tops is all you need.  Leave the detailed comments for the <remarks/> section.
4. Don’t explain something in terms of itself.  The documentation is where you should expound on what’s going on and, in some cases, why.  Say you have a custom “ICoolThing” interface and you implement that in a “ReallyCoolThing” class.  A bad <summary/> would be, “An implementation of the ICoolThing interface that is really cool.” That’s not at all helpful - it doesn’t tell you anything.  Instead, try something like, “Cool thing used to render XML doc comments.” (Or whatever it’s used for.)  Explaining something in terms of itself isn’t clarifying, it’s just redundant.
5. Write in complete sentences…  Writing code is a very terse experience.  There’s a grammar, and it [generally] reads well enough,  but it’s a different beast than writing documentation. Documentation is where you need to describe in full, complete sentences and paragraphs what’s going on.
6. …But be straightforward and don’t go overboard with verbosity.  Basically, “know when to say when.”  You’re not writing a legal document.  You’re not writing a scientific research paper.  (Or maybe you are, but you know what I mean.)  Don’t “fluff up” your docs with extra language.  Don’t over-formalize the language.  Make it easy to read, explain what’s going on, and call it a day.
7. I can has grammarz?  Use proper spelling, grammar, and punctuation.  If you’re not confident in your writing abilities, have someone who is good at this proofread for you.  (Or, better still, integrate the proofreading into your code review process. You have a code review process, right?)  It may seem unimportant, but these things can make your documentation far easier to understand and may even give users more confidence in your code. (If the person writing the code can’t write a decent sentence, would you really have the confidence that all of the error handling and such is done right?)  The only time you can write your docs with bad spelling, grammar, and punctuation is if you’re writing in LOLCODE.
8. Read your own documentation.  Once you’ve written your docs, read them through to see if they make sense.  This sounds like common sense, but it’s amazing how many times I’ve seen docs get written and the author never actually read through them to see if they were intelligible.  Docs aren’t a write-only stream - read and revise as necessary.

9. Remember that whitespace doesn’t render.  Or at least not like you think it does.  Don’t forget that you’re writing in XML - throwing in a standard line break isn’t going to actually get you onto a new line.  So, for example, this:

   /// <remarks> /// This is the first line. /// This is the second line. /// </remarks>

   Renders as:

   This is the first line. This is the second line.

   Create paragraphs by using <para>...</para> tags (similar to the <p>...</p> in HTML - put your content between the <para> and </para> tags).  Generally you won’t actually want single line breaks anywhere because in the 80% case, you’ll actually be wanting to use a different construct - a list, a table, or paragraphs.  A revised version of the above block would be:

   /// <remarks> /// <para> /// This is the first line. /// </para> /// <para> /// This is the second line. /// </para> /// </remarks>

   The exception to this rule is the <code/> tag - whitespace is respected in there because it’s assumed to be a code snippet.

10. Hyperlink, hyperlink, hyperlink.  The beauty of XML doc comments is how easily you can cross-reference related topics.  If you’re talking about one method from the documentation on another method, use a <see /> tag to add a link to the relevant method right from the comment body.  If there are related topics that are really important but may not have been linked to from the body of the comment (or maybe they warrant special attention via additional links), use <seealso /> tags at the bottom of your comment block.

11. Use special markup for reserved words.  One of the extensions that NDoc added is the ability to use <see /> tags on certain reserved words.  When the documentation rendering engine sees these reserved words, it can apply special formatting or perform common expansions on them.  The syntax for this is <see langword="reservedword" />.  For example: <see langword="true" /> …renders as… true …and… <see langword="null" /> …renders as… a null reference (Nothing in Visual Basic)

    The recognized words are:

    • abstract
    • false
    • null
    • sealed
    • static
    • true
    • virtual
12. Add valid code samples wherever possible.  Nothing helps a developer like seeing a code snippet.  The key is to not only add these snippets where possible (in a nested <code/> tag inside the <example/> tag) but also to make sure they’re valid.  This is sometimes a hard task.  A good way to come up with a valid snippet is to actually write a small demo program and copy the code from that - that way you know the snippet works.
13. Don’t forget to XML encode entities.  Again, you’re writing XML, so don’t forget that < needs to be <, > needs to be >, and so on.  The compiler will generally catch errors for you, but sometimes things work when they shouldn’t and you’ll get some unexpected results.
14. Update your doc when you update your code.  The worst problem you’ll run into is that the doc you wrote six months ago doesn’t actually reflect what the code is doing.  It’s easy to overlook updating your docs because the build doesn’t break when your docs are wrong.  Incorrect documentation is actually worse than bad documentation because while bad docs are hard to read, incorrect docs will potentially lead your users to spin wheels wondering why things aren’t working as documented.
15. Make documentation a priority.  Don’t let documentation be a second class citizen to cranking out the code.  Give it equal rights in your development process and let developers on your team know that documentation is important, too.  If documentation isn’t seen to be important, it won’t get the focus it needs.  Add documentation to your checklist of what needs to be finished before a task is marked complete.

There are a few tools out there that can help you improve your XML doc comment writing experience.  My two favorites are:

• GhostDoc- Gives you a starting point for writing XML documentation.  Really helpful when you’re implementing interfaces or overriding methods because it can grab the docs from the base method and use that as your starting point.
• CR_Documentor - Shows a preview of what your documentation will look like when rendered. Also adds some XML documentation templates to the editor context menu.
• CodeRush Templates
  • Expand templates to write documentation quickly and consistently.

Write the docs you’d like to see. Start with that, and the rest should fall into place for you.

The One Laptop Per Child foundation has their “Give One, Get One” program going on where you buy two of these little XO laptops and one comes to your house, one gets donated to a child in a developing country.  It’s $400, and $200 of that is tax-deductible (the cost of the laptop that gets sent to the developing country).  The rest goes toward the laptop that hits your hot little hands.  (Ostensibly to give to a child in your life, but for me it’s more likely a toy to hack.)

A charity to help teach kids computing skills? Oh, hellz yeah.  I bought mine; have you got yours?

Sunday was my first trip to an Ikea store ever.

I never really understood what the big deal with Ikea was.  Everyone I talked to who’d been there would start salivating when I talked about Ikea, barely able to contain their feelings about how awesome it is.  My uncle (and many, many others) swears by the meatballs.  I’ve got friends who would only ever shop at Ikea (and no other stores, ever) if they had that option.  I just never got it.

Sunday, Jenn and I packed up and, with our friends Angela and Keaka, headed to the Portland Ikea store.  I went with a skeptical mindset, fully expecting to be underwhelmed.

Ikea freaking rocks.

Ikea is sort of like… well, if General Electric or Mitsubishi decided to open a store that just sold everything they made, that’s what Ikea is.  They sell everything.  Batteries.  Furniture.  Art.  Food.  Toys.  Seriously, it’s just overwhelming.  Angela told us she usually allocates about three hours to an Ikea trip and I can see why - you can’t actually make it through the place in much under two.  We took two and a half hours.

I didn’t expect to buy anything.  I’ve always seen the catalog and not been really much interested in anything.  I ended up purchasing a chair, an ottoman, a rug, and some artwork for our front room.  All put together, it’s got a really nice lounge sort of feel to it, and it’s nice to get some furniture in that room.  We’ve been in the house for a few years now and have been looking for the right stuff.  I think a key factor here was price - we got all that for less than $750.  Not bad.

Of course, less than 24 hours went by before Jenn’s cat peed on the ottoman and the rug.  Maybe the low cost paid off.  (As far as I can tell, the stains came out, but still.  Come on.)

We also had the obligatory meatball lunch in the cafe there and I liked it.  I’m not all crazy over the meatballs, but they’re pretty decent.  I also discovered that I like lingonberry and several of the desserts there.

So I’m an Ikea convert.  I finally get it.  I don’t know that I’ll have a Pavlovian response or anything, but if someone says they want to venture out to Ikea, I’ll go.  As long as we have at least three hours to kill.

I posted the pictures I took at the MS Patterns & Practices summit over on Picasa.  If you’re interested, go check it out.

Microsoft Patterns & Practices Summit 2007

Went to Hanselman’s Nerd Dinner last night and must say, it was well worth it.  A lot of folks turned out for it, including Omar Shahine, Adam Kinney, John Lam, Jason Haley… oh, yeah, and Lutz Roeder.  A great social event and a piroshky?  Hellz yeah.

Oh, I bugged Lutz about it again, and he’s letting me releaseCR_Documentoras open source.  Apparently there was some political hoopla going on before that would have been bad had I released it, but that seems to have passed so it’s cool now.  All you folks wanting new features and wondering why I’ve been stagnating - now you can contribute.  I’m going to finish up my refactor of it so it’s stable and get it out there. This definitely gives me a renewed interest in finishing up the next release.  Yay!