Documenting Code

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