Comments

Comments

Within each source code file that you edit, you will need to provide certain comments as documentation. Visual Studio® automatically generates some source code files that you will not need to modify — you don’t need to add comments to those files.

At the top of each file in which you provide code, add a comment of the following form:

/* filename.cs
 * Author: Name 
 */

where filename.cs is the name of the file, and Name is the name of the primary author. The primary author will either be you or, for files provided for you, the name of the original author of that file. Whenever you use someone else’s code, it is important that you give them credit for it. (To fail to do this is plagiarism.) Thus, if one of your source files was originally written by Rod Howell, leave his name as the author. If you have modified a file originally written by someone else, below the Author line, insert a line of the following form:

/*
 * Modified by: Your Name
 */

Prior to each class, structure, enumeration, field, property, and method, place a comment documenting its use. This comment should be delimited by /// on each line. When you type /// immediately above a class, structure, enumeration, field, property, or method, the IDE will automatically insert additional text to form a comment stub such as:

/// <summary>
/// 
/// </summary>

<summary> and </summary> are XML tags, which are understood by the IDE. Between these tags, you should insert a summary of the program component you are documenting, including any requirements that must be satisfied by the calling code in order for the method to work properly. For example:

/// <summary>
/// Indicates whether this structure is empty.
/// </summary>
private bool _isEmpty;

If the program component being documented is a method with at least one parameter and/or a non-void return type, additional XML tags will be generated by the IDE. For each parameter, <param> and </param> tags will be generated. You should insert a description of the use of that parameter between these tags. If the method has a non-void return type, <returns> and </returns> tags are generated. You should insert an explanation of the value being returned between these tags. For example:

/// <summary>
/// Computes the number of times a given string x
/// occurs within a given string y.
/// </summary>
/// <param name="x">The string being searched for.</param>
/// <param name="y">The string being searched.</param>
/// <returns>The number of occurrences of x in y.</returns>
private int Occurrences(string x, string y)
{

}

Visual Studio often generates warnings when it cannot verify that the value being assigned to a non-nullable variable is not null. In cases where you can determine that the value will not be null, you are allowed to remove the warning by inserting ! after the value. In such cases, prior to this line, insert a comment explaining why this value is not null. For example:

string line;
while (!input.EndOfStream)
{
    // Because input isn't at the end of the stream, ReadLine won't return null.
    line = input.ReadLine()!;
}

Comments should also be used within methods to explain anything that is not obvious from the code itself.