Databases
StackOverflow2013
Postsdbo
PODocumentation comments in C#: What are technical reasons to prefer /// or /**
Body
 

Note that there are some explanatory texts on larger screens.

plurals
  1. PODocumentation comments in C#: What are technical reasons to prefer /// or /**
    text
    copied!<p>Appendix A of the C# language specification deals with documentation comments and it states that there are two forms:</p> <blockquote> <p>single-line-doc-comment: <BR> /// input-charactersopt<BR> delimited-doc-comment: <BR> /** delimited-comment-textopt */<BR></p> </blockquote> <p>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. </p> <p>I've also read in the book "C# for Java Developers" by Jones and Freeman the following:</p> <blockquote> <p>Code documentation comments are preceded by three forward slashes, as shown here:<BR> <code>/// A single line documentation comment.</code><BR> 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.</p> </blockquote> <p>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.</p> <p><code>**edit**</code> Some people asked to show a sample. Here is the sample:</p> <pre><code>/// &lt;summary&gt; /// Performs a Method1 calculation on two strings /// &lt;/summary&gt; /// &lt;param name="arg1"&gt;The first string&lt;/param&gt; /// &lt;param name="arg2"&gt;The second string&lt;/param&gt; /// &lt;returns&gt;The number 3&lt;/returns&gt; public static int Method1(String arg1, String arg2) { return 3; } /** * &lt;summary&gt; * Performs a Method2 calculation on two strings * &lt;/summary&gt; * &lt;param name="arg1"&gt;The first string&lt;/param&gt; * &lt;param name="arg2"&gt;The second string&lt;/param&gt; * &lt;returns&gt;The number 3&lt;/returns&gt; */ public static int Method2(String arg1, String arg2) { return 3; } </code></pre> <p>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?</p>
 

Querying!

 
Guidance
An individual column

Larger individual text columns get their own page to allow for proper reading.

SQuiL has stopped working due to an internal error.

If you are curious you may find further information in the browser console, which is accessible through the devtools (F12).

Reload