Comments - C# Mastery Course

now have learned about ifs al sees Wiles and various other code elements there's still one thing that makes this code not professional and not how I would write the code this topic is highly preferential and I stand on the side where fewer developers do than don't this is not to say this is right or wrong and you will often find that the right way of doing things is the least traveled path simply following other people is not the right answer and not the way to go just as I try and teach in this course don't simply follow what I do use your own mind and make your own decisions but the topic we're going to talk about in this lesson there's comments now comments to me are highly important in code when I started developing at 10 years old I didn't like comments I liked my code as small and compact as possible I removed all whitespace all extra lines I liked it to feel small compact and tiny I even changed my font size to really small this is a kind of feeling when you start writing code that you want it to be efficient and the size physically on-screen of your code has a mental impact on your thought of how efficient code is also and unfortunately a lot of developers tend to be very egotistical and full of themselves they feel like they're the smartest person in the world and that comments are there for beginners this is an incredibly poor misconception of comments and in fact comments are only written by high-level developers and the mid-level developers that think they are high-level developers and don't write comments stand out to those that are above them in skill level this isn't to say that all high-end developers write comments but working in the industry since I've been 10 years old and working for huge companies multi-billion dollar companies multiple times over and still to this day I can tell you now I have never seen a top-end developer not write comments I will explain in this lesson why it is so important and why it holds a very strong opinion for me when writing code of course you are completely free to ignore my advice and not write comments but I will give you my reasons as to why I write comments so let's get stuck into some code and see how comments can improve our application I showed how to write comments in a previous lesson just briefly let's begin by commenting the introduced Savi method call to do that we simply do two forward slashes and the line turns green this is an indication that there is a comment comments are typically green unless you have changed your koala theme now the point of a comment is to explain your code and it's to explain it in any way you want it isn't to explain something technically challenging such as a developer trying to understand the code it's simply to explain your code as if you were talking to another person in real life that is the best way to think about it it's also used then when you come back to your code to read through what you were thinking in your head so if I was going to explain this coach you now and I want to explain this introduce sabi call I will take a quick look myself at what we wrote and we basically output a message so here we could say introduce our savvy robot because this is effectively a little mini robot it's talking to the end user it's introducing itself and then it's telling it what it's going to do so the importance of this call in terms of the application overall even though it's very basic is that the point of this line of code if a non developer was to come to you and say well what's the point of putting this line of code here what does this do you would say it's to introduce our savvy robot so that the user knows what to do the next line of code here is ask for date of birth and this is where many mid-level developers get confused they feel like putting a comment here now stating ask the user for their date of birth they feel like this is pointless Cody well because comments are often called code they feel that this is irrelevant because the method name indicates that it says ask for date of birth and you can clearly see and understand that we are setting a variable from the result of Astrid a to birth now all that is true but they have completely missed the point of a comment as I just mentioned a comment isn't to explain to a lesser developer with less knowledge than yourself what your amazing code is capable of and what it does and that they need a comment to understand your code that is not the point of comments perhaps when you start out as a developer and you progress that as the point of comments but once you start to use them correctly or in the sense that I use them and feel they are correct they are nothing to do without me to explain what the line of code below does technically it's about describing your application you should be able to write an application free of any code and be able to read this method and know what it will do so we've removed the code from this main method and we can see already that our application should introduce our sorry robot and ask the user for their date of birth anybody that isn't a developer can understand this anybody that is a developer can understand this the importance of comments is to be able to read through your code like a book and the purpose of that is because it is far quicker to read a comment than it is to read code now this example somebody might try to say well I can see this bit quicker than reading a full sentence but in your head you still have to interpret what that means the mental capacity required to read asked for date of birth look at the variable and make the assumption that this statement means ask the user for their date of birth has taken up more brain power than simply reading the comments one by one and knowing what the application does this is the first use of comments and it should explain each line of code as we go the next use of comments is to comment the actual methods themselves this is typically more for a developer than it is for quickly reading through code so comments inside of methods and the two forward slash comments are generally so you can screw up over your code quickly read comments and know what's going on but let's look at what happens in introduced Savi if we are writing code and we open up the parentheses for this method you can see the intellisense shows nothing of importance if we open up console.writeline instead you can see we get this text that comment isn't a license and that is coming from code comments so our introduced Savi method should have a comment so that the developer consuming this method knows and has feedback that this method does what they presume it does to add comments to methods that become exposed violent a license we go the line above the method signature and put three forward slashes as soon as we do that we get a summary written for us inside of here now we can write our comment just as before introduce Savi the robot to our user now if we hover over introduce Savi you can see already we now have the white text explaining that this method introduces Savi robot to our user so we need to comment our methods as well as commenting inside of our methods let's continue down this class and comment the whole class here is the odd exception where I may not comment because there is one line of code because it's also something that is happening and without it we don't know and with it the code may actually have bugs and perhaps this was meant to write this text to a file or perhaps we are writing this text to a file and not to the screen we should still comment the purpose of this line we had a comment and we can simply put output message to user we don't need to explain that it's going to the console because this application is a console application and it's also not meant to be overly technical these comments inside of here again if you remember also you can read your code like a book and non developers could read your comments to a degree and understand your code next we get to the ask for date of birth method so again this is where the method explanation is more developer-friendly and developer specific because it's when we are writing our actual code here and we want some feedback when we open the parentheses as to what we might need to do or expect in code it isn't the same as this kind of general comment so here we should explain that we ask the user for their date of birth until it is given in a correct format and we should probably mention that this loop is indefinite until they do or in this case this call will not return until a valid date is entered or the application is terminated so now here what we have done already is make a slight mistake we have explained in the summary this is what the method does then we've gone on to give it further description that are specific and it's really a remark we're saying that this call will not return until a valid date is entered it's not the primary purpose of this method the method is to ask the user for the date of birth so this part of the comment here we want to cut out and instead if we go between the returns and the summary and we open up an angle bracket you can see here we have example which is to show example code we have a completion list which we will get into in future as well as exceptions includes and various other things but one that we like here is remarks if we put remarks here and paste our comment again if the comment goes too far over the screen I tend to like to go down a line and split it so it's nice and easy for people that aren't on extra-wide monitors the remarks would show if we use tools that generate public online web documentation of code and this XML comment is used to generate that typically you will see this when there is public api's with documentation for developers to read and if you are in Visual Studio and this wasn't your code you would press f12 to jump to the code and the remarks would show for example if we go to console dot write line and press f12 it would take us to something like this we can expand the comments and the remarks would be shown here so for a developer wanting to know something about a method call they would typically press f12 to jump to the source code or in this case the signature of the method and the remarks would be here so we use remarks where they are less important as the overall statement but something of importance for the developer to know if they run into trouble or want to read up about this method so don't worry too much about the separation of remarks and summary for now feel free to just write everything in summary but method summary comments are very important to give you professional code when you hover over it looks much better and it gives the user some feedback that the method they are calling is doing what they expect this is again important because perhaps we have refracted our code and change this method and it's now doing something else so we change this method now to say delete file and then we went to our code and it said delete file if we had no comments this might look like what we expected to do but any developer that uses it would open this off and see ask the user for that date of birth so it gives an instant hint that something is wrong in code so as well as helping the code be well-documented it's also a sign that if these two things become out of sync the developer has potentially done something wrong or simply forgot to keep things in sync and that brings me on to another thing that many developers will not like about comments is the basic excuse that they will become out of sync we copy and paste this function because we have something similar to write and we change the function name to ask user for their day of birth and we don't bother updating this comment now we have the issue I mentioned above however that is simply a fact that the developer has done something wrong they have copy and pasted code and whenever you do that any could develop a nose to pay extra special attention to the code you have copy and paste it and update everything about that code including comments to make sure the new code is what it should be copy and pasting can be very dangerous in code because of that fact that we become lazy and just paste code without rereading what should happen the returns block is used to specify what is returned from the function now I am bad for writing returns there technically you're not meant to write returns because that is the point of returns it's saying this is what has returned instead we should simply say the date of birth the user entered because that is what is being returned now along with remarks an example and returns right now when you hover over you simply get the summary however Visual Studio will very soon support showing the remarks and the examples and various other elements in the intellisense this is thanks to fact that now more and more people are becoming aware of using comments correctly and this additional information is being added if you wanted it now you could use an add-in such as resharper which can show more details in the intellisense but I would avoid installing such a heavy add-on to visual studio instead for now you can always f12 in to read more details about the comments also a very good place to read up on comments and exactly what I am explaining here is this link so doc Microsoft comm /en - us four slash net four slash c-sharp for its lush code doc Microsoft have got very good at making documentation better these days and it's a very good resource for explaining all of these tags inside of the method comments so moving on from now explaining this method we should now finish and comment this method so here now again think about what it is we are writing when we all learning code and explaining it or when we are creating this method in the first place and talking to ourselves what do we say when we wrote this line of code we needed to set this value up because we wanted to store this variable check that it was within the range we wanted and loop until it was so the requirement here was to store the initial value or in this case create an initial 'invalid value that's out of range so we will say create out of range initial value that explains that we are expecting this to be out of range and it's out of range of the wild check so we expect that max value should be greater than now so with this comment and we read it without the code we know that we expect to create an out of range initial value that's easier than reading this and then trying to remember why we wrote that line even this really simple code you open it up and when you see this line of code and you don't go any have I said to you right what is the point of this line no developer could accurately tell me why we have done this they caught by reading the remaining code but again remember comments are about saving mental capacity why read this line of code then read all this line here then make the assumption that this line is doing something all along having no validation that what it does is even correct the point of the seemingly simple comment is incredibly important in helping to want prevent errors in code and miss types and to help you to skim your code very fast so hopefully you can start to see the picture if you think about code where code is missing because it could be potentially invalid or not written yet or you simply haven't read that code yet then does the line of code you are seeing make sense as to what it's doing don't write comments with the presumption that things will be explained below write comments that make sense at this point in time and don't require further reading to understand what your application is doing at this point in time so now we move on to the while loop what is the point of this while loop now we don't want to explain the inner workings of this while loop we want to explain this one line of code here so don't go stating that loop until the user has entered a valid date of birth and then we turn the date of birth because there's bit we loop until it's a valid date of birth this bit is about entering yet and this bet is about returning that code so those comments will be split the purpose of this specific line is until the date of birth is greater than today and that's it now typically when this is a statement that hasn't finished this is something we are explaining until the date of birth is greater then what I typically put three dots this is entirely my convention and something I've come up with over the years and it simply helps to indicate to the reader and to me when I'm reading that this statement isn't in whole complete it is explaining something that is going to be further explained inside so an if statement in an Alf statement I will very commonly say if something dot dot and then the line after will finish off you're free to use this style as I do or you can ignore it so now the code says until the date of birth is greater than today which is exactly what is here and again if the code was accidentally written like this this comment would now give a hint that there's something wrong with code this line of code is to simply tell the user what to do so tell the user to enter a date of birth this line of code is to read their response this line of code is now to try and pass that value to a date so we say and remember this isn't if so my comments typically start with everyone the statement is if and what is happening if we successfully convert the date to a date time if we successfully convert the user's text to a date time but again we don't want to be over technical in comments so instead we should write if the user entered a valid date because that's all that matters try to keep your comments free of technical code jargon try to think of it that somebody that isn't a developer or perhaps a developer that simply doesn't understand something in code yet can still make use of these comments so the point of here is has the user entered a valid date this code defines if that's valid by trying to pass it to a date time offset but the comment does not need to specify that so instead if the user entered a valid date dot then what do we do we set the checked date to users given date then on the else it's quite simply otherwise or else I tend to write otherwise because that's how I would normally speak I wouldn't typically say else when I'm talking I would say otherwise inform user they entered invalid date now it's much easier to understand our method by simply reading the comments one last line here before we're done is to return the result so let's just now delete this code so you can see more clearly what I mean about comments and what you should be doing when you read code if we delete all the code you can see now here is my complete method and let's read it we create an out of date range initial value until the date of birth is greater than today so in this case here now we have specified we create an out of date range but then we say until the date of birth is greater than today or what is date of birth we haven't specified date of birth here so what we need to do is establish in the comments what we are talking about let's quickly put the code back in and let's fix this so this variable needs some kind of mention in the code so that the comments can understand each other such as here the checked date we used here so let's use that definition that's in the comments up here create checked date with initial out of range value and then until the checked date it's greater than today so now we have some correlation between comments let's delete the code again and you don't have to delete code you would typically just read your comments but when starting out it's a really good show to read your comments to see if they make sense with the absence of code so let's try again create check to date with the initial out of range value until the checked date is greater than today so that now makes sense and you can tell with the indentation level also where we are then going into things and you will notice the comments that end up indenting the comment above has the dot dot so it indicates that when this happens something else is going to happen so until the check date is greater than today tell the user to enter their date of birth read their response if the user entered a valid date set the check date to use his given date otherwise inform user they entered invalid date and then returned result so this now makes perfect sense without any code and by reading gates and without any knowledge of code this is how we would explain what our method is doing and it's a very good way of explaining the method if we put our code back in now and do the opposite let's delete the comments if I were to now ask a senior developer to look at this code and with three seconds to spare explain to me what this code now does line by line they would not be able to the point of fact is they could make presumptions that you are setting a variable to max value then you are checking if that value is greater than today then you are writing something to the console then you are reading the response then you are passing some value so they can interpret code as they go and they can do it fairly quickly on basic code but they have no understanding of the point of this method they can say while it's asking for date of birth but what if we call this method something like Hello which developers often do they get lazy with the names of comments just as they get lazy with the names of methods so having a reliance on names and code being correct and a developer skill level to allow any develop to even understand what this basic method does is much harder without comments it also takes up much more time this is a really simple method and yet it still takes time to interpret this code mentally to go through and understand it and then we are also presuming the code is free of bugs which it never is if we introduce comments into our code there is absolutely no doubt that as long as we haven't written our comments wrong which we shouldn't because that is the whole point this is what we are thinking this is what we want our code to do then the comment is going to be correct the comment is your truth this is what we want our code to do then the code below is attempting to do what the comment asks so hopefully you can see the high importance of writing comments it may seem like a lot of superfluous information such as return the result when we are clearly returning a result however what if we didn't mean to return the result or even if we did perhaps the result is meant to return something different like the inverse of the result there are many times in code where things that seem simple and might be simple at that point in time might have their purpose changed and without to comment the backs up what we thought at that point in time when we wrote the code we could introduce a book I've seen this so many times you would not believe and the biggest issue with buggy code has always the lack of comments while commented code with well maintained comments has far fewer bugs than code without comments all you have to do as a developer is get used to the feeling that I don't want this extra line making my method look larger in fact you should instead treat your comments with just as much importance as your code don't try to squash up code and remove as many things as possible to make it small I did this when I started out developing and it was an obsession with wanting things to be compact because I didn't want long code you simply have to grow out of that as you mature as a developer the size of your code has no relevance to the efficiency of the code and sometimes code that is actually written in a clearer way is better than more efficient code because it's easier to interpret and the requirements of that method may not be about ultimate efficiency writing code is about being able to understand maintain and progress that code comments go a huge way to making your code maintainable and usable in a team there is much more to learn about comments mostly in things like the summaries remarks exceptions but the main thing to try and understand is the principles of comments don't just write a comment for the sake make it written for purpose and also make sure your comments flow like a story one after the other and make sense with each other just like your code can't have while date of birth to is greater than today because the value above mentions date of birth so your comments just like we did our definition of check date should flow through the comments so that when reading them without the code it still makes sense you can see a lot of thought has to go into writing good comments it isn't as simple as just making a quick note nor should it be it should be a well-thought-out plan of what your application and what your methods are doing it's what we do before we write code we think to ourselves this is what I want to achieve this is what I want to do those are the type of things the comments end up explained is the thought pattern the purpose and the point of your code so hopefully you will start using comments from today onwards and you will see the major benefits as you go forward

Channel: AngelSix

Views: 4,312

Keywords: c#, software, development, wpf, vue, vue js, animation, web design, wevb, .net core, asp.net core, free, open source, git, tutorial, beginners, real world, javascript, html, css

Id: uVdGIuVuSmo

Length: 30min 49sec (1849 seconds)

Published: Sat May 23 2020