C# Course for Absolute Beginners – Lesson 1.6

Next Lesson

Introduction

In this lab we’re going to demonstrate how to add code comments, and explain their importance.

Step 1: Understanding Why Code Comments are Used

A code comment is code or other text that is written in your program but isn’t compiled. it isn’t processed by the .NET Framework Runtime. You may be wondering, "Why would anyone want to write code that doesn’t get processed or compiled?"

- Code comments allow you to add an explanation to remind yourself (or other programmers) exactly what you were trying to accomplish in a given code block.

- Code comments allow you to temporarily remove code from the compilation process. This allows you to disable code that may be causing errors. Commenting out a line of code is a typical practice by developers in an effort to debug, or to see what the code would be like if they tried something from a different approach. The comments allow developers to do this without losing any of the work that they have already done.

- Code comments allow you to remind yourself that there’s unfinished work that you’ll need to revisit at some future point – just like a note to self.

Step 2: Commenting a Single Code Line

We’ll use the code from the last lab for the first example. In this program, we have a single line of code that we know contains an error – we can see the red line notifying us of the error. If we were to try to run this program, we would receive an additional warning message that our program contains errors. In this scenario, imagine that we need to run this program. We don’t want to delete the line because we plan on fixing the bug tomorrow.

To comment out a single line, set your cursor just before the beginning of the code. Press the forward slash button on your keyboard twice. Notice that the whole line turns green – this let’s us know that the line is commented, and is no longer compiled. We can now run the program, and in the future we have the option of fixing this line, ignoring it or deleting it. If in the future we wanted to reintroduce this line of code to the program, simply delete the two forward slash marks.

Step 3: Commenting Multiple Lines of Code

The double forward slash method works very well for a single line of code, but imagine that there was an entire section of code that needed to be commented. It would be laborious to go through and comment each line individually. Fortunately, there’s a better way.

(1) To begin the comment, type a forward slash followed by an asterisk ( /* )

(2) To end the comment, type an asterisk followed by a forward slash ( */ )

Notice that every line between the two marks is now in green, showing that we’ve commented out multiple lines. Nothing in the comment block will be processed. As your programming skills develop you’ll find that you’ll often need to comment multiple lines, so it’s important to learn both the // and the /* nomenclature.

NOTE:
If you forget to close your comment, everything below the opening comment line will be commented. This means that none of the following code will work until you correct the oversight.

Step 4: Using Multi-Line Comments to Include Program Explanation Notes

Try this:

Use a forward slash and asterisk to start a code comment block, but don’t close it. Press the "Return" key on your keyboard several times. Notice that green asterisks are added.

Typically you would use this whenever you’re typing some notes about the code itself. For example, in the above image we’ve included a note that reminds us why we programmed this section of code. (You may have noticed that we’ve also included a reference to the book "The Hitchhiker’s Guide to the Galaxy" by Douglas Adams).

Step 5: Demonstrating the Importance of Closing the Code Comment Block

If you were to run this program, you would see that it fails.

(1) If you look at the Error List, you would see on lines 2, 3, and 4 that C# is expecting several closing brackets.

(2) You may be thinking, "But I see them on lines 30, 31 and 32 – so the closing brackets are there!"

The answer is that no, they aren’t there. Because we never ended the code comment block, the closing brackets are all commented out – meaning that they aren’t included. In fact the Error List even gives us that clue – in the first error listed it mentions that it expects an end to the code comment block.

By closing our code comment block, the closing brackets that follow on lines 30, 31 and 32 are now un-commented. The program will now run.

Step 6: Visual Studio IDE Code Comment Shortcuts

Next we’ll review a shortcut to commenting your code.

(1) Instead of manually typing the code comment marks, the Visual Studio IDE provides a button you can use. If you hover your mouse cursor over the button a button description box even appears.

(2) Notice that the button uses the two forward slash marks. We’ve previously used these to comment out a single line. You can use the button to comment out a single line without even highlighting it, or you can highlight multiple lines to comment out an entire selection.

Notice that there’s an Uncomment button right next to the first button. This works in much the same way – you can use this button to uncomment individual or multiple lines.

- To uncomment multiple lines simply highlight the section you wish to uncomment, and press the button.
- To uncomment a single line you can optionally highlight the line, but this is unnecessary. Simply set the mouse cursor anywhere in the line and press the Uncomment button.

Step 7: Including Active URLs Within Code Comments

Finally, you’ll learn how to create live hyperlinks within your comments.

Imaging the following scenario:

You found something that was particularly important for reference purposes for a section of code that you’re about to write. You know you’re going to pass this code off to somebody else who might not be familiar with a particular method or class in the .NET Framework Class Library. To solve this, you decide to include a link to the url in your code comments.

To accomplish this, simply type the url within your code comment. The Visual Studio IDE will automatically make this link clickable, so you or other programmers can easily access this link from the C# application.

Conclusion

In this lab, you learned what comments are and how they function. You learned that comments are used to leave notes to yourself or others, or to temporarily disable certain sections of code. You learned how to comment and uncomment both individual lines and groups of lines, both manually and using the buttons provided in the Visual Studio IDE. You also learned the dangers of forgetting to close a code comment block, and how that can create errors within your program. Finally, you learned to include URLs within your code comments to direct other programmers to important information. You’ll see code comments used throughout these labs. As the programs you create become more complex you’ll also appreciate the value code comments provide in testing and debugging.

Next Lesson