Discussion of nontrivial or non obvious design decisions is appropriate, but avoid duplicating information that is present in the code. It is too easy for redundant comments to get out of date. In general, avoid any comments that are likely to get out of date as the code evolves.
The frequency of comments sometimes reflects poor quality of code. When you feel compelled to add a comment, consider rewriting the code to make it clearer.
Note: Do not leave a lot of out-commented code in your source files. This is often very confusing to another programmer! Change history should be retrieved from the version handling system, not by leaving commented code behind.
When you wish to use block comments you should use the following style:
// Line 1 // Line 2 // Line 3
Use the built in functionality in Visual Studio for this. It's available on the "Text Editor" toolbar or via the shortcut keys [Ctrl+K, Ctrl+C] for commenting and [Ctrl+K, Ctrl+U] to uncomment.
Do not use old style block comment like:
/* Line 1 Line 2 Line 3 */
All non-private classes, interfaces, methods and properties should have a documentation tag comment. These are used to generate XML based API documentation. This is similar to how Java source is documented (JavaDoc). Visual Studio also uses these comments in the Object Browser to display brief description of members and their parameters.
The Visual Studio IDE has a feature called Smart Comment Editing that automatically generate and insert a documentation tag template for you. You activate this by writing /// just before the object to be documented.
For classes, events and other simple objects a summary tag is created.
Example 4: Simple documentation template
namespace Ifs.Fnd.AccessProvider { /// <summary> /// Provides functionality for server access /// </summary> public class FndConnection { ... /// <summary> /// Raised before a server invocation /// </summary> public event ServerInvokeEventHandler Invoking;
When documentation tags are created for a method, Visual Studio automatically generates XML tags for parameters and return values as well.
Example 5: Documentation tag for a method
/// <summary> /// Invoke a select statement /// </summary> /// <param name="recordType">Type of records to generate in the resultset.</param> /// <returns>The resultset</returns> public Ifs.Fnd.Data.FndDataTable ExecuteReader(string recordType)
Next example also shows how you can insert a code example that will be generated into the documentation together with the rest.
Example 6: Documentation tag with code example
/// <summary> /// Connect string to server on format server:port /// </summary> /// <example> /// <code> /// ... /// FndConnection conn = new FndConnection(); /// conn.ConnectString = "lkprnd1:63080"; /// ... /// </code> /// </example> public string ConnectString { get { return this.connectString; } set { this.connectString = checkConnectionString(value); } }