Later Today: ASP.NET Tutorial 2: Introduction to C#

ASP.NET Tutorial 3: Commenting & Documenting Code

This tutorial introduces code comments – including general comments, intellisense comments, and code regions. Code comments are little notes that you can leave right inside your code to help yourself or other developers that may need to look at your code.

Developing good code commenting habits is absolutely vital for every developer. When you’re projects get even remotely complicated, you will run into situations where you won’t be able to remember what on earth you were doing last, or why you did something a certain way to begin with. Furthermore, if anyone ever inherits your code, comments can make the nearly insurmountable task of deciphering it much more palatable. More often than not, however, it will be you deciphering your own code – so save yourself a lot of time later by spending a little up front and writing good comments.

Basic code comments come in two varieties: single-line comments, and multi-line comments.

> Single-Line Comments

This section covers general code commenting.

Single-line comments are usually ideal for short notes that you want to put on a line by itself, or following a line of code.

You create a single-line comment by typing forward-slash twice ( // ), followed by whatever note you’d like to leave. Everything following the double-slashes on that line is considered a comment. The following examples demonstrate different uses (green text are comments).

Single-Line Comment Example #1:
//This is a single-line comment

Single-Line Comment Example #2:
//Set a value for the strCoffeePot variable
string strCoffeePot = CoffeeMaker("water","beans");

Single-Line Comment Example #3:
iCountVisits = ++iCountVisits; //Increments iCountVisits by 1

Tip: You can also use comments to disable code. This is most handy when you want to turn off certain bits of code without deleting them (usually for testing purposes).

Single-Line Comment Example #4 (Disabling Code):
//int iCountVisits = ++iCountVisits; //Increments iCountVisits by 1

> Multi-Line Comments

This section covers general code commenting.

Multi-line comments have two particular uses: leaving large notes (several sentences to several paragraphs), or disabling large chunks of code. There are two shortcuts for multi-line comments, one shortcut that BEGINS the comment ( /* ), and another shortcut that ENDS it ( */ ). Everything between the two shortcuts is considered a comment.

The following examples demonstrate different uses.

Multi-line Comment Example #1:
/*
This is a multi-line comment.
*/

Multi-line Comment Example #2:
/*
To whosoever reads this, I am so very, very sorry for the state of this
code. It's labyrinthine and convoluted logic has driven me nigh unto
the depths of despair, so that I long for the sweet embrace of kind
and merciful death. I pity you, and wish you all patience of the ages.
*/

Multi-line Comment Example #3 (Disabling Code):
/*
string strCoffeePot = CoffeeMaker("water","beans");
iCountVisits = ++iCountVisits; //Increments iCountVisits by 1
*/

> Regions

This section discusses the use of regions to make your code easier to navigate.

Did you know that Visual Studio will let you “collapse” (aka “minimize”) and “expand” chunks of code? If you look at the left side of the Text Editor window you may see some of those familiar [+] or [-] symbols you’re used to seeing in various tree views. These are automatically available for methods, classes, and namespaces… but what if you have a big chunk of code that you want to collapse without collapsing the entire method?

This happens often – for instance, you may have a few lines of code inside a method that deals only with sending an email, and you wish it didn’t take up so much screen space. Well, you can wrap it in region tags, which serve no other purpose than making those [+] and [-] icons appear (for the region). Hence, you can take a big chunk of code and collapse it into a single line comment.

C#:
#region This is like a single-line comment, describing the contents of the region
//lots of code goes here
#endregion

When collapsed, the above example would look like this…

This is like a single-line comment, describing the contents of the region

No Comments

Post a Comment

You must be logged in to post a comment.

RSS Twitter LinkedIn Facebook
Doing neato things with JavaScript, please wait...