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
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
- XML Documentation Tutorial
- Tips and Tricks for Visual Studio
- Productivity Tips for Visual Studio
- Visual Studio Blog
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"
Related Discussions
Have questions about this video? Start a discussion with the community and Treehouse staff.
Sign upRelated Discussions
Have questions about this video? Start a discussion with the community and Treehouse staff.
Sign up
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 upYou need to sign up for Treehouse in order to set up Workspace
Sign up