VB.NET from beginner to advanced programmer Part 20 - Advanced Comments

[Vswe]

Welcome to the VB.NET tutorial series: "VB.NET from beginner to advanced programmer" which will take you from the very beginning to be a good programmer. VB.NET is a good first language for new programmers so this 21 part long series is written for completely beginners but it will also works perfectly fine if you already know another programming language.


VB.NET from beginner to advanced programmer

1. Introduction and Installation
2. Objects and Events
3. Variables
4. The basic data types
5. Logical Operators
6. Relational Operators
7. If statements Then
8. Arithmetical Operators
9. Loops Part 1
10. Arrays
11. Loops Part 2
12. Try Catch statements
13. Subs and Functions
14. Difference between Scopes
15. Select Statements
16. Multidimensional arrays
17. Structures
18. Classes
19. Enumerations
20. Advanced Comments
21. Compiling Directives

Now we're going through most of the things but there's still some few more parts. As early as in part 2 I showed you how to comment your code properly but now I will show you some more advanced commentating. The reason I teach you this so late in his tutorial series is because these comments is more like a part off, for example variables, functions and classes, so then you have to know what that is.

These more advanced comments works for:

• Classes
• Structures
• Enums
• Variables
• Constants

To insert these more advanced comments you easily just type three 's(like this ''') in front of the thing you want to comment. Now some text will be added where you can add the comments. Observe that the text which is added is just the standard, you can add more things too and the standards is not always the same either.


The most standard text looks like this:

''' <summary>
''' 
''' </summary>
''' <remarks></remarks>

If you know some XML or HTML you identify this as two empty blocks, one called summary and one called remarks, and this is exactly what it is. So here we simply adds a summery and some more info in the remarks.


And now the reason, why are we doing this? Of course to get a program who is easier to navigate through while creating it as the "standard comments" we learned about in part 2. The reason we have a special syntax for this type of comments is because these comments will now be added as a comment to the specific function, variable etc. I'll show you:


Firstly I create a variable called myTestVariable:

    Private myTestVariable As Object

Then I write the three 's:

''' <summary>
''' 
''' </summary>
''' <remarks></remarks>
Private myTestVariable As Object

And then fill the summery and the remarks:

''' <summary>
''' A variable used for testing.
''' </summary>
''' <remarks>This variable is used in Vswe's Tutorial "VB.NET - From Beginner to advanced programmer."</remarks>
Private myTestVariable As Object

So now when the commentating is done we can for example view the summery when using it, as shown in the image below:





When using Enums, Classes, structures and Public variables you can find all info about them(including remarks) in the object browser (Go to it by pressing F2), looking like this:



Observe that I changed the scope of the variable to Public.




But remember I said that summary and remarks is not the only things you can fill in. For example when adding comments to a function you'll also got one for each parameter and one for the return value:

''' <summary>
''' 
''' </summary>
''' <param name="parameter1"></param>
''' <param name="parameter2"></param>
''' <returns></returns>
''' <remarks></remarks>
Private Function myTestFunjction(ByVal parameter1 As Integer, ByVal parameter2 As String)

    Return parameter1 + parameter2.Length

End Function

So if I fill this out:

''' <summary>
''' A function used for testing.
''' </summary>
''' <param name="parameter1">The base number</param>
''' <param name="parameter2">The String to take the length from</param>
''' <returns>An integer with the value of the sum of parameter1 and the length of parameter 2</returns>
''' <remarks>A function which takes two parameters, one integer and one string to get an Integer value equals to the length of the string + the base number found in parameter1.</remarks>
Public Function myTestFunjction(ByVal parameter1 As Integer, ByVal parameter2 As String)

    Return parameter1 + parameter2.Length

End Function

Two example images on this function:






So all this makes your program looking more professional, easier to create since you'll see what everything does just by the summery and just generally make it easier for you. This was it. See you later.

[Jordan]

I actually like the .NET style of commenting. It is important to have enough comments in your code. I've heard many beginners say "I understand what it does" but they haven't gone back and looked at their own code 1 month later, or even a year later. Those moments can produce rapid "wtf" statements.

Nicely done! +rep