Documentation comments in C#: What are technical reasons to prefer /// or /**

Question

Appendix A of the C# language specification deals with documentation comments and it states that there are two forms:

single-line-doc-comment:
/// input-charactersopt
delimited-doc-comment:
/** delimited-comment-textopt */

is there a preference? I notice a tendency to prefer the single-line-doc-comment format but I do not know if there are technical or practical reasons besides people choosing from an aesthetic point of view.

I've also read in the book "C# for Java Developers" by Jones and Freeman the following:

Code documentation comments are preceded by three forward slashes, as shown here:
/// A single line documentation comment.
The C# specification also recommends use of the familiar /** token to identify multiline documentation comments. However version 7.00 of the C# compiler does not support this syntax.

I've been unable to verify that the latest versions of the csc do not work with the multiline syntax. As far as I can tell this syntax works just fine.

**edit** Some people asked to show a sample. Here is the sample:

/// <summary>
/// Performs a Method1 calculation on two strings
/// </summary>
/// <param name="arg1">The first string</param>
/// <param name="arg2">The second string</param>
/// <returns>The number 3</returns>
public static int Method1(String arg1, String arg2)
{
    return 3;
}
/**
 * <summary>
 * Performs a Method2 calculation on two strings
 * </summary>
 * <param name="arg1">The first string</param>
 * <param name="arg2">The second string</param>
 * <returns>The number 3</returns>
 */ 
public static int Method2(String arg1, String arg2)
{
    return 3;
}

So the question, restated, is which form is preferable, are there technical or other reasons to prefer the documentation comment style of Method1 in the sample, above, or Method2 in the sample, above?

Answer 1

Info I've been able to gather since posting this question confirms that even though csc /doc: will accept either format, the single-line format has some advantages over the multi-line format:

1) In Visual Studio, IntelliSense will give you info clarifying the arguments you are passing in a method invocation expression as you are typing, regardless if you originally documented your method with /// or /**. However, Visual Studio will give you support in writing documentation comments using prefills only if you use the /// format. For example, if you place the cursor above a method declaration in Visual Studio and press / three times you will see a context-specific template generated for you like this:

    /// <summary>
    /// 
    /// </summary>
    /// <param name="arg1"></param>
    /// <param name="arg2"></param>
    /// <returns></returns>

This doesn't work if you position the cursor on the method and press /,*,*.

2) The single-line format allows a cleaner layout of the documentation comments since each line starts with the same indentation, all lines of the block can be used, and each line of comment information is left-aligned.

3) There are, in general, advantages to using the single line style in that single line comments are free to contain the */ token whereas multiline comments are are not; and they are generally easier to work with if you are copying/pasting pieces of comments from one place to another inside an editor.

4) There is also evidence that the C# compiler favors the single line format, if you consider how csc.exe deals with adjoined documentation blocks. Consider a declaration like this:

   /**
     * <thiscutetag>some info</thiscutetag>
     */
    /**
     * <theothercutetag>more info</theothercutetag>
     */
    public static void Main() { }

When passing through csc /doc: the documentation will be generated as though the contents of both blocks modified the Main method. This behavior is not intuitive, but becomes intuitive if you transform the two adjoined multiline comment blocks into two adjoined sets of single-line comments, as follows:

    /// <thiscutetag>some info</thiscutetag>
    /// <theothercutetag>more info</theothercutetag>
    public static void Main() { }

Answer 2

I have never encountered any limitations when using asterisks over the double (or triple) slashes. For whatever reason, the C# community has decided to use double slashes for comments.

Interestingly it appears the double slash comments came out of C++ and Java. Below I have included a list of languages an what denotes a comment in the language:

1. ALGOL 60 - ; (semicolon)
2. Assembly Languages - ; (semicolon)
3. Ada, mySQL - -- (two dashes)
4. C++/Java - // (two slashes)
5. FORTRAN 90 - ! (exclamation mark)
6. Perl, TCL, UNIX Shell, mySQL - # (hash sign)
7. Visual Basic .NET - ' (apostrophe)

The following are example of tools using the double slashes as single line and double line comments.

Visual Studio Highlight a block of code and use the key combinations Ctrl + K + C and the code is commented out using the single line double slashes.

Ghost Doc Ghost Doc is a tool that auto generates documentation for the method. It use the triple slash notation. It's my understanding that the triple slash with the use of XML elements in the comments allows tool such NDoc and Sandcastle generate MSDN-style HTML Help format.

Atomineer Pro Atomineer Pro is another tool that will generate method level documentation from the method name and parameter names. It also used the triple slash notation by default.

MSDN C# Coding Standards The C# coding standards say to use the double slash, and not to use the block comments.

iDesign C# Coding Standards While iDesign is not Microsoft, I've always felt they were a bit of an authority in the C# community. They have published a C# Coding Standard document which states the double notation is the preferred method.