Heads up! To view this whole video, sign in with your Courses account or enroll in your free 7-day trial. Sign In Enroll

Preview

Start a free Courses trial
to watch this video

Sign up for Treehouse

Documenting Code

5:47 with Dean Davidson

In this video we will show you how to create self-documenting code using XML comments and manage your incomplete code by using commenting conventions that generate Tasks.

Further Reading

Technical Debt: Technical Debt (also known as design debt or code debt) is "a concept in programming that reflects the extra development work that arises when code that is easy to implement in the short run is used instead of applying the best overall solution"

Documenting your code is a good practice to help other developers understand what 0:00
you're doing, but 0:04
it can also help your future self understand how or why you did something. 0:05
Every developer I know has written something only to come back 0:10
to it a year or two later and think to themselves what was I thinking? 0:13
Luckily for you, I'm about to show you some powerful tools that go beyond simple 0:17
comments and can help make your code easier to read use and maintain. 0:21
I think my calculate shipping cost method is pretty self-explanatory. 0:27
It takes in some parameters and returns the shipping costs right? 0:31
Let's try calling that method from another class. 0:35
Number of items is pretty easy. 0:42
I have three items, item weight, well, what kind of weight are we talking about? 0:44
Are we using pounds or kilograms as the unit of measurement? 0:51
I happen to know that I meant pounds because I wrote the method, but 0:54
somebody else would have to dig through the implementation to figure that out. 0:57
Now that I'm thinking about it, when calling this method, it's not 1:01
obvious what units of measurement the item size and distance are using either. 1:04
I need some XML documentation comments in my method. 1:08
These comments will allow Visual Studio to offer IntelliSense help to 1:11
anybody who calls my method. 1:14
You might be familiar with this if you've ever knows that visual studio offers some 1:16
hint text when you are calling methods that are part of the .Net Framework. 1:19
In addition to being useful in IDE you can compile your project with 1:23
the /Doc option and the compiler will find these comments and 1:27
create an XML documentation file for your app. 1:30
See the teachers notes for more information. 1:33
To let Visual Studio know that I intend to create an XML comment in the line above my 1:42
method signature I'll type three forward slashes based on my method signature, 1:47
Visual Studio generated the XML for me. 1:52
The summary field is just a summary of what your method does. 1:55
Number of items is pretty simple. 2:05
For item weigh I'll note that this is the combined weight of your items in pounds. 2:14
For items size I'm expecting width times height in inches. 2:26
For distance I am expecting the distance they are trying to ship the item in miles. 2:38
[SOUND] In the returns property, 2:42
I can describe what this method returns in greater detail. 2:46
I'll note that it returns a decimal that represents the shipping cost in US 2:54
dollars. 2:58
[NOISE] Now 2:58
if I go back to where I was trying to call the calculate shipping cost method 3:07
you can see our XML documentation appears in context. 3:11
As I cycle through each property, 3:17
I have are documentation handy and IntelliSense guides me through how 3:19
to use this method without me having to understand every line of code in it. 3:22
This next trick will help you keep track of things you want to refine in your code 3:34
in the future. 3:37
In my calculate shipping cost method, I actually want to take into account 3:38
different shipping carriers, but I don't have time to implement that, and 3:42
I need to gather more information on carrier specific shipping charges. 3:45
The current implementation is fine but I want to make sure to revisit this method. 3:49
To have Visual Studio generated task I will make a comment that starts with 3:55
the word to do in all caps to make note of this. 3:59
Now if I bring up my task list by pressing Ctrl+\,T or 4:13
selecting it from the view menu, that comment shows up as a task. 4:16
I can get to the line number by double clicking on the task. 4:23
The undone keyword can also be used. 4:29
The hack keyword can be used to denote areas where you've taken shortcuts that 4:32
you want to revisit in the future. 4:36
For example if you're working on a complex multithreaded app and 4:38
you solve a race condition error and you're not even fully sure why your update 4:41
solved the error, you probably want to put a hack comment in there. 4:45
I sometimes write hack comments when I'm dealing with external services in 4:49
libraries, and they're performing a way that I don't believe they should. 4:52
For example, this method that I think should accept strings with up to 30 4:55
characters in them, for some reason it returns a really and useful error. 4:59
I found a workaround and I will make note of it as a hack and move on. 5:03
Well, that's it. 5:20
This is by no means a comprehensive list of every feature in Visual Studio. 5:21
But if you use each of these items effectively, it'll really save you time, 5:25
make you stand out among your peers and help you write better code. 5:29
In the teachers notes, you'll find links to Microsoft's Visual Studio tips and 5:32
tricks page as well as the Visual Studio blog. 5:37
The blog is a nice way to stay up to date on the latest features of Visual Studio 5:40
as they are released. 5:44
Have fun and happy coding. 5:45

You need to sign up for Treehouse in order to download course files.

Sign up