Write Readable Code and Comments for Windows Forms Applications - How to code comments

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. Figure 3-8 shows you how to code comments.

The basic idea is that you start a comment with an apostrophe. Then, anything after the apostrophe is ignored by the compiler. As a result, you can code whatever comments you want.

In this figure, you can see four lines of comments at the start of the procedure that describe what the procedure does. You can see one-line comments at the start of blocks of code that describe what the statements in those blocks do. And you can see one example of a comment that follows a statement on the same line.

Although some programmers sprinkle their code with comments, that shouldn’t be necessary if you write your code so it’s easy to read and understand. Instead, you should use comments only to clarify code that’s difficult to understand. The trick, of course, is to provide comments for the code that needs explanation without cluttering the code with unnecessary comments. For example, an experienced Visual Basic programmer wouldn’t need any of the comments shown in this figure.

One problem with comments is that they may not accurately represent what the code does. This often happens when a programmer changes the code, but doesn’t change the comments that go along with it. Then, it’s even harder to understand the code, because the comments are misleading. So if you change the code that has comments, be sure to change the comments too.

Incidentally, all comments are displayed in the Code Editor in a different color from the words in the Visual Basic statements. By default, the Visual Basic code is blue and black (blue for Visual Basic keywords and black for the rest of the code), while the comments are green. That makes it easy to identify the comments.

A procedure with comments

  Private Sub btnCalculate_Click(ByVal sender As System.Object, _
          ByVal e As System.EventArgs) Handles btnCalculate.Click

  ' ========================================================
  ' This procedure calculates the discount and total for an invoice.
  ' The discount depends on the invoice subtotal.
  ' =======================================================

  ' Determine the discount percent
      Dim discountPercent As Decimal
      If txtSubtotal.Text >= 500 Then
          discountPercent = 0.2
      ElseIf txtSubtotal.Text >= 250 And txtSubtotal.Text < 500 Then
          discountPercent = 0.15
      ElseIf txtSubtotal.Text >= 100 And txtSubtotal.Text < 250 Then
          discountPercent = 0.1
      Else
          discountPercent = 0
      End If

  ' Calculate the discount amount and invoice total
      Dim discountAmount As Decimal = txtSubtotal.Text * discountPercent
      Dim invoiceTotal As Decimal = txtSubtotal.Text - discountAmount

  ' Format the discount percent, discount amount, and invoice total
  ' and move these values to their respective text boxes
      txtDiscountPercent.Text = FormatPercent(discountPercent, 1) 
      txtDiscountAmount.Text = FormatCurrency(discountAmount)
      txtTotal.Text = FormatCurrency(invoiceTotal)

      txtSubtotal.Select()      ' Move the focus to the Subtotal text box

  End Sub

Coding recommendations

1. Use comments only for portions of code that are difficult to understand.
   
2. Make sure that your comments are correct and up-to-date.

Description

1. Comments are used to help document what a program does and what the code within it does.
   
2. 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. 
    
3. 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 statements. Another way to comment out one or more lines of code is to select the lines and click on the Comment or Uncomment button in the Text Editor toolbar (see figure 3-10).

Figure 3-8.   How to code comments

Please check back next week for the continuation of this article.

Comments On: Write Readable Code and Comments for Windows Forms Applications

>>> Be the FIRST to comment on this article!

Buy this book...

This article is excerpted from chapter three of Murach's Visual Basic 2008, written by Anne Boehm (Murach, 2008; ISBN: 1890774456). Check it out today at your favorite bookstore. Buy this book now.