Coding Skills for a Windows Form Application - How to code comments
(Page 3 of 5 )
Comments are used to document what the program does and what specific blocks and lines of code do. Since the C# compiler ignores comments, you can include them anywhere in a program without affecting your code. Figure 3-8 shows you how to code two types of comments.
First, this figure shows a delimited comment at the start of a method. This type of comment is typically used to document information that applies to an entire method or to any other large block of code. You can include any useful or helpful information in a delimited comment such as a general description of the block, the author’s name, the completion date, the files used by the block, and so on.
To document the purpose of a single line of code, you can use single-line comments. Once the compiler reads the slashes (//) that start this type of comment, it ignores all characters until the end of the current line. In this figure, single-line comments have been used to describe each group of statements. In addition, single-line comments have been used at the end of some lines of code to clarify the code.
Although many 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 C# 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 C# statements. By default, the C# code is blue and black (blue for C# keywords and black for the rest of the code), while the comments are green. That makes it easy to identify the comments.
A method with comments
private void btnCalculate_Click(object sender, System.EventArgs e)
{
/**********************************
* this method calculates the total
* for an invoice depending on a
* discount that’s based on the subtotal
**********************************/
// get the subtotal amount from the Subtotal text box
decimal subtotal = Convert.ToDecimal(txtSubtotal.Text);
// set the discountPercent variable based
// on the value of the subtotal variable
decimal discountPercent = 0m; // the m indicates a decimal value
if (subtotal >= 500)
{
discountPercent = .2m;
}
else if (subtotal >= 250 && subtotal < 500)
{
discountPercent = .15m;
}
else if (subtotal >= 100 && subtotal < 250)
{
discountPercent = .1m;
}
// calculate and assign the values for the
// discountAmount and invoiceTotal variables
decimal discountAmount = subtotal * discountPercent;
decimal invoiceTotal = subtotal - discountAmount;
// format the values and display them in their text boxes
txtDiscountPercent.Text = // percent format
discountPercent.ToString("p1"); // with 1 decimal place
txtDiscountAmount.Text =
discountAmount.ToString("c"); // currency format
txtTotal.Text =
invoiceTotal.ToString("c");
// move the focus to the Subtotal text box
txtSubtotal.Focus();
}
Description
- Comments are used to help document what a program does and what the code within it does.
- To code a single-line comment, type // before the comment. You can use this technique to add a comment on its own line or to add a comment at the end of a line.
- To code a delimited comment, type /* at the start of the comment and */ at the end. You can also code asterisks to identify the lines in the comment, but that isn’t necessary.
Figure 3-8 How to code comments
Next: How to work with the Text Editor toolbar >>
More C# Articles
More By Murach Publishing
|
 This article is excerpted from chapter three of the book Murach's C# 2005, written by Joel Murach (Murach, 2005; ISBN: 9781890774370). Check it out today at your favorite bookstore. Buy this book now.
|
|
