VS TnT #11: fastest way to self-documenting code!
Friday, December 17, 2010 3:11 PM
We know we're SUPPOSED to document our code, but how can get Visual Studio to help us out? Read on for a quick trick!
TnT: 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!
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, well...you just whip it out right?
Next, you want to go use it. Cool, here's what VS Intellisense looks like.......uh....hhhhmmmmm a bit bland right?
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.
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.
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.
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.
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!