Computer Programming I :: Lessons :: Comments
Comments are short sentences that describe aspects of a computer program. Comments are ignored by the compiler and there are two types of comments that can be used in C#.
End of line comments include all text following a double slash (//) and are useful for comments that can fit easily on a single line.
Multiline comments include text on any lines between the opening /* and closing */. These are very useful if you want to temporarily deactivate a portion of your code.
While you can add a comment at the end of every line of code you write this is usually not necessary. Comments are meant to make a program more legible and easier to maintain. Here are some guidelines to follow when writing comments:
- Include a multiline comment at the start of your program that discusses the purpose of the program.
- Variables should have names that describe what they do so do not include comments with variable declarations.
- Major blocks of code such as methods should be preceded by a comment explain their purpose.
- Include comments with complex sections of code when the purpose or function of that section of code isn't obvious at first glance.
White space is nearly as important as good commenting in keeping your program legible and easy to maintain. Consider the following two blocks of code:
Although the code above is not C# (it's PHP, a language mainly used for web applications) the code on the right is much easier to read than the code on the left. This is because space is included to separate the lines and tabs are used in certain points. Visual Studio will add tabs and white space for you, but it is still an important principle to keep in mind.
A comment header is a longer comment at the top of your code. This comment is meant to give general information about the code such as the author, when it was last updated, and other information that is helpful to know right away. In Computer Programming I you should have a comment header with the following information:
- Your name
- The names of anyone in class you helped
- The names of any people or websites you used to get help with your code
- The algorithm for your project
You comment should look like the following at the top of your code:
/* Jon Snow I Helped: Arya Stark, Samwell Tarly, The Night's Watch, Stannis Baratheon I Was Helped By: Ghost the Direwolf, Ygritte 1. Create a random number generator 2. Choose a random number 3. Based on the random number, show a picture and a quote */
It is important to note the name of EVERYONE who helped you with your project to avoid accusations of plagiarism. While you shouldn't directly copy someone else's code, you are free to have someone help you with your own code.
You may decide to write one of your programs in class with a partner. This is know as pair programming and is a common practice in the computer science industry. If you do choose to write a program with a partner, here are the requirements you must meet:
- Include both of your names in the comment header.
- One person should serve as the driver and type the code.
- One person should serve as the navigator and talk with the driver about the code.
- Switch roles every 25 minutes or so.
There should NEVER be a point in the pair programming process where the members of the pair are not talking to each other. Pairs that aren't communicating will be broken up. The driver should not be doing the typing and thinking. Thinking about what to write should be a collaborative process.