Documenting your code is a good practice to help other developers understand what

you're doing, but

it can also help your future self understand how or why you did something.

Every developer I know has written something only to come back

to it a year or two later and think to themselves what was I thinking?

Luckily for you, I'm about to show you some powerful tools that go beyond simple

comments and can help make your code easier to read use and maintain.

I think my calculate shipping cost method is pretty self-explanatory.

It takes in some parameters and returns the shipping costs right?

Let's try calling that method from another class.

Number of items is pretty easy.

I have three items, item weight, well, what kind of weight are we talking about?

Are we using pounds or kilograms as the unit of measurement?

I happen to know that I meant pounds because I wrote the method, but

somebody else would have to dig through the implementation to figure that out.

Now that I'm thinking about it, when calling this method, it's not

obvious what units of measurement the item size and distance are using either.

I need some XML documentation comments in my method.

These comments will allow Visual Studio to offer IntelliSense help to

anybody who calls my method.

You might be familiar with this if you've ever knows that visual studio offers some

hint text when you are calling methods that are part of the .Net Framework.

In addition to being useful in IDE you can compile your project with

the /Doc option and the compiler will find these comments and

create an XML documentation file for your app.

See the teachers notes for more information.

To let Visual Studio know that I intend to create an XML comment in the line above my

method signature I'll type three forward slashes based on my method signature,

Visual Studio generated the XML for me.

The summary field is just a summary of what your method does.

Number of items is pretty simple.

For item weigh I'll note that this is the combined weight of your items in pounds.

For items size I'm expecting width times height in inches.

For distance I am expecting the distance they are trying to ship the item in miles.

[SOUND] In the returns property,

I can describe what this method returns in greater detail.

I'll note that it returns a decimal that represents the shipping cost in US

dollars.

[NOISE] Now

if I go back to where I was trying to call the calculate shipping cost method

you can see our XML documentation appears in context.

As I cycle through each property,

I have are documentation handy and IntelliSense guides me through how

to use this method without me having to understand every line of code in it.

This next trick will help you keep track of things you want to refine in your code

in the future.

In my calculate shipping cost method, I actually want to take into account

different shipping carriers, but I don't have time to implement that, and

I need to gather more information on carrier specific shipping charges.

The current implementation is fine but I want to make sure to revisit this method.

To have Visual Studio generated task I will make a comment that starts with

the word to do in all caps to make note of this.

Now if I bring up my task list by pressing Ctrl+\,T or

selecting it from the view menu, that comment shows up as a task.

I can get to the line number by double clicking on the task.

The undone keyword can also be used.

The hack keyword can be used to denote areas where you've taken shortcuts that

you want to revisit in the future.

For example if you're working on a complex multithreaded app and

you solve a race condition error and you're not even fully sure why your update

solved the error, you probably want to put a hack comment in there.

I sometimes write hack comments when I'm dealing with external services in

libraries, and they're performing a way that I don't believe they should.

For example, this method that I think should accept strings with up to 30

characters in them, for some reason it returns a really and useful error.

I found a workaround and I will make note of it as a hack and move on.

Well, that's it.

This is by no means a comprehensive list of every feature in Visual Studio.

But if you use each of these items effectively, it'll really save you time,

make you stand out among your peers and help you write better code.

In the teachers notes, you'll find links to Microsoft's Visual Studio tips and

tricks page as well as the Visual Studio blog.

The blog is a nice way to stay up to date on the latest features of Visual Studio

as they are released.

Have fun and happy coding.