Breadcrumbs

[Skillful]

Hello guys.
Here is my new topic on Comments in VB.NET
Hope you like it!

Comments can be used to document what the program does and what specific blocks or lines of code do. Since the Visual Basic compiler ignores comments, you can include them anywhere in a program without affecting your code.

How to comment?

A comment is preceded by an apostrophe. The code of line after the apostrophe is simply ignored by the compiler.
To code a comment, type an apostrophe followed by the comment. You can use this technique to add a comment on its own line or to add a comment after the code on a line.

Often when you code, you may want to comment out an entire block of code statements. Under normal circumstances, to do so you must Comment out each line individually.

Another way to comment out one or more lines of code to select the lines and click on the Comment or UnComment button in the Text Editor toolbar.

Shortcut: You can use Ctrl+C and Ctrl+U to Comment or Uncomment selected lines of text.

Tips to Comment your code

Use comments only for portions of code that are difficult to understand
Comments are used to help document what a program does and what the code with it does. Keep the comments simple and direct. Avoid ASCII art, jokes, poetry and hyper verbosity.
Make sure that your comments are correct and up-to-date. There is no point in commenting correctly on code if the comments are not changed with the code. Both code and comments must move in parallel, otherwise the comments will actually make life more difficult for developers who maintain your code.
During testing, you can comment out lines of code by coding an apostrophe before them. This is useful for testing new statements without deleting the old statement.
Align comments in consecutive lines

For multiple lines of code with trailing comments, align the comments so they will be easy to read.

Code: Select all

Const level As Integer = 100                 ' The level mark is constant to 100 can't be changed
Const turnaround As Decimal = 34.5       ' The turnaround is constant and can't be placed more 

Some developers use tabs to align comments, while others use spaces. Because tab stops can vary among editors and IDEs, the best approach is to use spaces.
Use paragraph comments

If you comment is very long in line of text break into paragraph show it can be seen in a single view.

Instead of writing like this:

Code: Select all

' Author CoderBoy1201. Xyz Company. Created on 10th March 2011 12:13:19 A.M.

Break into different lines like this:

Code: Select all

' Author CoderBoy1201. 
' Xyz Company. 
' Created on 10th March 2011 12:13:19 A.M

Consistent style of commenting

Some people believe that comments should be written so that non-programmers can understand them. Others believe that comments should be directed at developers only.

Comments are consistent and always targeted to the same audience. Comments should target to developers and non-developers.
Don't insult the reader's intelligence

Avoid obvious comments such as:

Code: Select all

Dim age As Integer = 34
        If (age >= 18) Then      'if age is greater than 18 a person can vote
            Console.WriteLine("Can Vote")
        End If

This wastes your time writing needless comments and distracts the reader with details that can be easily removed from the code.

Comment code while writing it

Add comments while you write code and it's fresh in your memory. If you leave comments until the end, it will take you twice as long, if you do it at all. "I have no time to comment," "I'm in a hurry," and "The project is delayed" are all simply excuses to avoid documenting your code. Some developers believe you should write comments before code as a way to plan out your ultimate solution.

For example:

Code: Select all

Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click

        'On click of button check priopr that values are entered properly in order
        'Validate date for range and data types
        'ask before submitting values
        'make this entry in the database
         ' then you can follow your code

    End Sub

Write comments as if they were for you (in fact, they are)

When it comes to commenting code, think not only about the developers who will maintain your code in the future, but also think about yourself. In the words of the great Phil Haack:

"As soon as a line of code is laid on the screen, you're in maintenance mode on that piece of code."

As a result, we ourselves will be the first beneficiaries (or victims) of our good (or bad) comments.

Write comment in a polite manner

Avoid rude and harsh comments. You never know who may read these comments in the future: your boss, a customer, or the pathetically inept developer you just insulted. So maintain your respect and dignity.

The golden rule.

Let the code speak for itself. You code should be written in such a way that everyone should easily understand it.

For example:

Code: Select all

Dim str As String = "Puran Singh Mehra"
        Dim num As Integer = 36
        Dim binWriter As New BinaryWriter(File.OpenWrite("c:\myfile.dat"))
        binWriter.Write(str)
        binWriter.Write(num)
        binWriter.Close()

Conclusion

Hope the article would have helped you in understanding comments and their usage and importance in coding. Proper usage of comments makes your code easily to understand and improve performance.

If you like my tutorials then please give me +rep!
Credits : VBDotNetHeaven

[hungryhounduk]

yeah a good tutorial on Commenting your Code

keep it up

Chris

[Usman55]

Really nice tutorial. Covers the basic things! I personally don't like commenting. Actually I don't know how to comment lol. If I knew, I would surely add them. +rep

[Scottie1972]

Original Thread can be found here: ( http://www.vbdotnetheaven.com/UploadFil ... VBNET.aspx )
Thread Created By: Puran Mehra August 27, 2009