Adding Comments to Your Code


One of the simplest things you can do to reduce bugs from the beginningand make tracking down existing bugs easieris to add comments to your code. A code comment is simply a line of text that Visual C# knows isn't actual code and therefore ignores. Comment lines are stripped from the code when the project is compiled to create a distributable component, so comments don't affect performance. Visual C#'s code window shows comments as green text. This makes it easier to read and understand procedures. Consider adding comments to the top of each procedure stating the procedure's purpose. In addition, you should add liberal comments throughout all procedures, detailing what's occurring in the code.

Did you Know?

Comments are meant to be read by humans, not by computers. Strive to make your comments intelligible. Keep in mind that a comment that's difficult to understand isn't much better than no comment at all. Also remember that comments serve as a form of documentation. Just as documentation for an application must be clearly written, code comments should also follow good writing principles.


To create a comment, precede the comment text with the two forward slash characters (//). A simple comment might look like this, for example:

// This is a comment because it is preceded by double forward slashes.


Comments can also be placed at the end of a line of code, like this:

int intAge;     // Used to store the user's age in years.


Everything to the right of and including the double-slashes in this statement is a comment.

Visual C# also supports a second type of comment, one that allows for comments to span multiple lines without forcing you to add // characters to each line. Such a comment begins with an open comment mark of a forward slash, followed by an asterisk (/*), and the comment closes with a close mark of an asterisk followed by a forward slash (*/). For example, a comment can look like this:

/*     Chapter 15 in Sams TY Visual C# 2005 focuses on debugging code; something most developers spend a lot of time on.  */


By adding comments to your code procedures, you don't have to rely on memory to decipher a procedure's purpose or mechanics. If you've ever had to go back and work with code you haven't looked at in a while, or had to work with someone else's code, you probably already have a great appreciation for comments.

Double-click the button now to access its Click event and add the following two lines of code (comments, actually):

// This procedure divides 100 by the value entered in // the text box txtInput.


Notice that after you type the second forward slash, both slashes turn green.

When creating code comments, do your best to do the following:

  • Document the purpose of the code (the why, not the how).

  • Clearly indicate the thinking and logic behind the code.

  • Call attention to important turning points in code.

  • Reduce the need for readers to run a simulation of code execution in their heads.

  • Comment your code as you are typing it. If you wait until the code is complete, you probably won't go back and add comments.

By the Way

Visual C# also supports an additional type of comment denoted with three slashes (///). When the Visual C# compiler encounters these comments, it processes them into an XML file. These types of comments are often used to create documentation for code. Creating XML files from comments is a bit advanced for this book, but if these features intrigue you, I highly recommend that you look into it.





Sams Teach Yourself Microsoft Visual C# 2005 in 24 Hours, Complete Starter Kit
Sams Teach Yourself Visual C# 2005 in 24 Hours, Complete Starter Kit
ISBN: 0672327406
EAN: 2147483647
Year: N/A
Pages: 248
Authors: James Foxall

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net