Tuesday, November 20, 2001 ..:: Home ::.. Register  Login
   TechTidBits (Blog)  

VS TnT #11: fastest way to self-documenting code!

Dec 17

Written by:
Friday, December 17, 2010 3:11 PM  RssIcon

Visual Studio Tips'n'TricksWe know we're SUPPOSED to document our code, but how can get Visual Studio to help us out?  Read on for a quick trick!

Visual Studio Tips'n'TricksTnT: RIGHT above a method or class header, type out three forward slashes "///" and watch VS give you 90% of your API documentation right before your eyes!

Shortcut: ///

Da "Peter" Version (aka, ya, ya, da verbose one)

As developers, we get paid to write code not documentation right?  But then why are we asked to write API docs?  Ok, ok that's for another discussion, but sometimes we do it just to help ourselves, to give US a bit of a clue.  Here's how you can get VS to do the brunt of the work and let you focus on your task at hand.

First off, when you're whipping up a method, just whip it out right?

Method without docs

Next, you want to go use it.  Cool, here's what VS Intellisense looks like.......uh....hhhhmmmmm a bit bland right?

Code without docs

Ok, now, we'll go back to the original method we want to get some help with.  Put your cursor above the method declaration (yup, in the line right above it) then type out three forward slashes "///".  You'll know you did it right if Visual Studio puts in a but of "stuff" for you!  I've added some parameters to help illustrate how useful this is.

Method with docs shell

Please notice, you have a shell right now, Visual Studio did 90% of the heavy lifting/typing for you.  Now all you got to do is fill in the blanks.

Method with docs filled in

Ok, so that's the hardest part.  But what's the point you say right?  The BIGGEST reason for doing this TnT is to help give yourself A CLUE when you goto use this method six months from now.  What what VS Intellisense shows you when called.

Code with docs help

Notice how you get A LOT more help now!  Ok, so you JUST typed out that text, you remember it all right?  But in six months from now, this will seems like the angels are singing to you and lifting your spirits like your first two morning coffees! haahha

Ok, next, I'd like to point out the last line there, it's the specific parameter help of the one you're on.

Code with docs help

Ok, so I've thrown in a few dummy parameters just for show, but they illustrate quite nicely IMHO this TnT.

This is all cool, BUT there is one caveat to all this.  If you were to change your mind and uuuhh update any of the parameters, you'll need to manually change the API docs yourself.  So if you're going to use this (which I strongly enourage you too HAHA), then try it AFTER you've settled on the API.

Now that you know how to get VS to help "self-document" your code, it's time to grab a coffee and get coding!

Location: Blogs Parent Separator TechTidBits

Your name:
Gravatar Preview
Your email:
(Optional) Email used only to show Gravatar.
Your website:
Add Comment   Cancel 
Copyright 1999-2012 by   Terms Of Use  Privacy Statement