1
00:00:00,410 --> 00:00:04,360
Documenting your code is a good practice
to help other developers understand what

2
00:00:04,360 --> 00:00:05,530
you're doing, but

3
00:00:05,530 --> 00:00:10,410
it can also help your future self
understand how or why you did something.

4
00:00:10,410 --> 00:00:13,210
Every developer I know has written
something only to come back

5
00:00:13,210 --> 00:00:17,590
to it a year or two later and
think to themselves what was I thinking?

6
00:00:17,590 --> 00:00:21,590
Luckily for you, I'm about to show you
some powerful tools that go beyond simple

7
00:00:21,590 --> 00:00:26,230
comments and can help make your code
easier to read use and maintain.

8
00:00:27,480 --> 00:00:31,380
I think my calculate shipping cost
method is pretty self-explanatory.

9
00:00:31,380 --> 00:00:35,390
It takes in some parameters and
returns the shipping costs right?

10
00:00:35,390 --> 00:00:37,709
Let's try calling that
method from another class.

11
00:00:42,660 --> 00:00:44,820
Number of items is pretty easy.

12
00:00:44,820 --> 00:00:51,000
I have three items, item weight, well,
what kind of weight are we talking about?

13
00:00:51,000 --> 00:00:54,410
Are we using pounds or
kilograms as the unit of measurement?

14
00:00:54,410 --> 00:00:57,410
I happen to know that I meant pounds
because I wrote the method, but

15
00:00:57,410 --> 00:01:01,130
somebody else would have to dig through
the implementation to figure that out.

16
00:01:01,130 --> 00:01:04,160
Now that I'm thinking about it,
when calling this method, it's not

17
00:01:04,160 --> 00:01:08,000
obvious what units of measurement the item
size and distance are using either.

18
00:01:08,000 --> 00:01:11,250
I need some XML documentation
comments in my method.

19
00:01:11,250 --> 00:01:14,320
These comments will allow Visual Studio
to offer IntelliSense help to

20
00:01:14,320 --> 00:01:16,390
anybody who calls my method.

21
00:01:16,390 --> 00:01:19,620
You might be familiar with this if you've
ever knows that visual studio offers some

22
00:01:19,620 --> 00:01:23,610
hint text when you are calling methods
that are part of the .Net Framework.

23
00:01:23,610 --> 00:01:27,290
In addition to being useful in IDE
you can compile your project with

24
00:01:27,290 --> 00:01:30,590
the /Doc option and
the compiler will find these comments and

25
00:01:30,590 --> 00:01:33,770
create an XML documentation file for
your app.

26
00:01:33,770 --> 00:01:35,590
See the teachers notes for
more information.

27
00:01:42,901 --> 00:01:47,680
To let Visual Studio know that I intend to
create an XML comment in the line above my

28
00:01:47,680 --> 00:01:52,535
method signature I'll type three forward
slashes based on my method signature,

29
00:01:52,535 --> 00:01:55,270
Visual Studio generated the XML for me.

30
00:01:55,270 --> 00:01:58,050
The summary field is just a summary
of what your method does.

31
00:02:05,348 --> 00:02:06,750
Number of items is pretty simple.

32
00:02:14,826 --> 00:02:18,410
For item weigh I'll note that this is the
combined weight of your items in pounds.

33
00:02:26,614 --> 00:02:29,970
For items size I'm expecting
width times height in inches.

34
00:02:38,470 --> 00:02:42,185
For distance I am expecting the distance
they are trying to ship the item in miles.

35
00:02:42,185 --> 00:02:46,427
[SOUND] In the returns property,

36
00:02:46,427 --> 00:02:54,291
I can describe what this method
returns in greater detail.

37
00:02:54,291 --> 00:02:58,057
I'll note that it returns a decimal
that represents the shipping cost in US

38
00:02:58,057 --> 00:02:58,635
dollars.

39
00:02:58,635 --> 00:03:07,600
[NOISE]
Now

40
00:03:07,600 --> 00:03:11,510
if I go back to where I was trying to
call the calculate shipping cost method

41
00:03:11,510 --> 00:03:15,010
you can see our XML documentation
appears in context.

42
00:03:17,630 --> 00:03:19,299
As I cycle through each property,

43
00:03:19,299 --> 00:03:22,693
I have are documentation handy and
IntelliSense guides me through how

44
00:03:22,693 --> 00:03:26,336
to use this method without me having
to understand every line of code in it.

45
00:03:34,177 --> 00:03:37,376
This next trick will help you keep track
of things you want to refine in your code

46
00:03:37,376 --> 00:03:38,880
in the future.

47
00:03:38,880 --> 00:03:42,020
In my calculate shipping cost method,
I actually want to take into account

48
00:03:42,020 --> 00:03:45,060
different shipping carriers, but
I don't have time to implement that, and

49
00:03:45,060 --> 00:03:48,399
I need to gather more information on
carrier specific shipping charges.

50
00:03:49,580 --> 00:03:53,720
The current implementation is fine but I
want to make sure to revisit this method.

51
00:03:55,519 --> 00:03:59,678
To have Visual Studio generated task I
will make a comment that starts with

52
00:03:59,678 --> 00:04:02,240
the word to do in all caps
to make note of this.

53
00:04:13,160 --> 00:04:16,388
Now if I bring up my task
list by pressing Ctrl+\,T or

54
00:04:16,388 --> 00:04:20,260
selecting it from the view menu,
that comment shows up as a task.

55
00:04:23,411 --> 00:04:26,330
I can get to the line number by
double clicking on the task.

56
00:04:29,880 --> 00:04:32,920
The undone keyword can also be used.

57
00:04:32,920 --> 00:04:36,620
The hack keyword can be used to denote
areas where you've taken shortcuts that

58
00:04:36,620 --> 00:04:38,790
you want to revisit in the future.

59
00:04:38,790 --> 00:04:41,670
For example if you're working on
a complex multithreaded app and

60
00:04:41,670 --> 00:04:45,260
you solve a race condition error and
you're not even fully sure why your update

61
00:04:45,260 --> 00:04:49,060
solved the error, you probably want
to put a hack comment in there.

62
00:04:49,060 --> 00:04:52,140
I sometimes write hack comments when
I'm dealing with external services in

63
00:04:52,140 --> 00:04:55,670
libraries, and they're performing a way
that I don't believe they should.

64
00:04:55,670 --> 00:04:59,530
For example, this method that I think
should accept strings with up to 30

65
00:04:59,530 --> 00:05:03,830
characters in them, for some reason
it returns a really and useful error.

66
00:05:03,830 --> 00:05:07,260
I found a workaround and I will make
note of it as a hack and move on.

67
00:05:20,116 --> 00:05:21,800
Well, that's it.

68
00:05:21,800 --> 00:05:25,880
This is by no means a comprehensive
list of every feature in Visual Studio.

69
00:05:25,880 --> 00:05:29,770
But if you use each of these items
effectively, it'll really save you time,

70
00:05:29,770 --> 00:05:32,880
make you stand out among your peers and
help you write better code.

71
00:05:32,880 --> 00:05:37,340
In the teachers notes, you'll find links
to Microsoft's Visual Studio tips and

72
00:05:37,340 --> 00:05:40,590
tricks page as well as
the Visual Studio blog.

73
00:05:40,590 --> 00:05:44,500
The blog is a nice way to stay up to date
on the latest features of Visual Studio

74
00:05:44,500 --> 00:05:45,890
as they are released.

75
00:05:45,890 --> 00:05:47,490
Have fun and happy coding.