This section describes the standards used when adding comments in Application Forms source code.
Comments can be added to the code to highlight nontrivial or non obvious design decisions, but avoid duplicating information that is already present in the code. 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. It's very easy for redundant comments to get out of date and be more confusing than helpful. In general, avoid any comments that are likely to get out of date as the code evolves.
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 under Edit -> Advanced -> Comment Selection. The functionality is also available as toolbar buttons on the "Text Editor" toolbar, or via keyboard shortcuts [Ctrl+K, Ctrl+C] to comment and [Ctrl+K, Ctrl+U] to uncomment.
Do not use old style block comment like:
/* Line 1 Line 2 Line 3 */
Note: Do not leave a lot of out-commented code in your source files. This is very confusing to another programmer! Change history should be retrieved from the version handling system, and not by leaving commented code behind.
All non-private classes, interfaces, methods and properties should have a documentation tag comment. These are used to generate XML based API documentation. 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 generates and inserts a documentation tag template for you. You activate this by writing /// just before the object to be documented.
For classes, events and other objects, a simple summary tag is created.
/// <summary> /// Column for handling configurations. /// </summary> public class cColumnConfiguration : cColumn
Figure 1: Documentation tag for a class.
When documentation tags are created for a method, Visual Studio automatically generates XML tags for parameters and return values as well.
/// <summary> /// Prepares data transfer and navigates to the given window. /// </summary> /// <param name="sFormName">Name of the window that shall be opened.</param> /// <returns>A Boolean value indicating if the launch was successful.</returns> public SalBoolean PrepareLaunch(SalString sFormName)
Figure 2: Documentation tag for a method.
The next example also shows how you can insert a code example that will be generated into the documentation together with the rest.
/// <summary> /// Gets or sets a value indicating the behavior of the column. /// <example> /// This example shows how to set the Flags property to NotQueryable and DefaultLOV. /// <code> /// column.Flags = ColumnProperties.NotQueryable | ColumnProperties.DefaultLOV; /// </code> /// </example> /// </summary> public ColumnProperties Flags
Figure 3: Documentation tag with code example.
Note: See the MSDN commenting guidelines for more info on using C# XML Comments.