8

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?

Mishax
  • 4,442
  • 5
  • 39
  • 63
  • The three slashes are used to comment a method or class and that comment is used by intellisense to describe the method. I dont think you can do the same with /** – crthompson Sep 04 '13 at 04:00
  • version 7 was Visual Studio .NET 2002 or 2003 (.net 1 and 1.1.x). – ps2goat Sep 04 '13 at 04:00
  • there is no c#7 - we don't even have a release of c# 6 yet .... – Code Uniquely Sep 04 '13 at 04:02
  • 3
    The best comment is the one you did not write. Express yourself in the code, not by comments that no one reads and maintain. Each time you write a comment it represents a failure of making the code clear. – Pierre-Luc Pineault Sep 04 '13 at 04:06
  • 1
    @paqogomez well I tried it in Visual Studio 2010 and intellisense does show me info placed in multiline documentation comments. – Mishax Sep 04 '13 at 04:09
  • 6
    @Pierre-LucPineault we're talking about documentation comments here. The purpose is to be read by people who do not have access to the source code. – Mishax Sep 04 '13 at 04:10
  • Interesting, then why would it matter which you use or what the preference was? (Not trying to be obstinate, just trying to understand) – crthompson Sep 04 '13 at 04:12
  • @Mishax there is not any code sample. This is not repated to stackoverflow – Shyam sundar shah Sep 04 '13 at 04:13
  • 1
    @Mishax Either a nice method name or complete external documentation? But if you _really_ want that clutter just type /// on a method and it'll spawn the template. – Pierre-Luc Pineault Sep 04 '13 at 04:14
  • 1
    @Mishax Have you seen this question - http://stackoverflow.com/questions/1745179/c-sharp-coding-style-comments – davidsleeps Sep 04 '13 at 04:45
  • @davidsleeps that is an interesting link, and no I did not see it so thanks for sharing. This link has useful info on the multiline vs singleline comment choice but I don't see anything about documentation comments – Mishax Sep 04 '13 at 04:55
  • @Mishax the only part I saw was from this answer http://stackoverflow.com/a/1745220/51507 mentioning the XML generated. – davidsleeps Sep 04 '13 at 05:16
  • 7
    I can't believe that we're putting the art of code documentation at the same level as internal comments whose purpose is to explain spaghetti code. (And it gets upvoted, too.) A descriptive method name is a must, yes, but it cannot *possibly* describe the changes in behavior in the case of overloads, the potential exceptions, the contract this method has in respect to its override candidates, etc. Don't mindlessly repeat mantras, people. The .NET documentation features may look like comments, but they're actually important metadata. – Theodoros Chatzigiannakis Sep 04 '13 at 21:09
  • 1
    Could the person who put the mention "This question may already have an answer here: C# coding style: comments 10 answers" please remove that because this question is specifically about documentation comments, not about comments in general, and yes I have seen that other page and no it does not contain useful information, it only contains incorrect information about documentation comments. – Mishax Sep 04 '13 at 21:10
  • Doxygen supports generating documentation from C# also, but I believe that it too supports both formats. – Ben Voigt Sep 04 '13 at 21:18

2 Answers2

7

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() { }
Mishax
  • 4,442
  • 5
  • 39
  • 63
0

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.

Chuck Conway
  • 16,287
  • 11
  • 58
  • 101
  • This addresses comments as the language feature, not the specially formatted comments sought and extracted by documentation tools. Besides, recent versions of C also support the C++-style `//`, and C++ also supports the C style `/* */`. – Ben Voigt Sep 04 '13 at 21:17
  • @BenVoigt In the second paragraph the question asks "*Is there a preference?*" I gave 5 examples of tools and coding standards that have chose double slash comments over asterisks block comments. In the last sentence the the question asks "*are there technical or other reasons to prefer the documentation comment style of Method1 in the sample, above, or Method2 in the sample, above?*" This is a rephrasing of his first question, but again the 5 examples demonstrate that the the double slash is preferred. – Chuck Conway Sep 04 '13 at 21:28
  • 1
    You're still focused on "the double slash". A double slash doesn't even start a documentation comment. All the other comments you compared to, are not documentation comments. Ctrl+K+C doesn't create documentation. – Ben Voigt Sep 04 '13 at 21:32
  • @BenVoigt You are splitting hairs. Either the slashes or the asterisks notation will be used. Developers are not going to co-mingle the styles. – Chuck Conway Sep 05 '13 at 02:48
  • @ChuckConway come to think of it I might do that - if I've got a comment tacked to the end of a line of code of I'll probably use the // because it's quicker and gives me less fuss.. On the other hand if I want to have comments inside a line of code (so code to the left, code to the right) I'll do the /* .. */ notation because that is the only way to do it. – Mishax Sep 05 '13 at 06:42