commenti di documentazione in C#: Quali sono motivi tecnici per preferire /// o/**

Question

Appendice A del linguaggio C# offerte specifiche con commenti di documentazione e si afferma che ci sono due forme:

a riga singola -doc-commento:
/// input-charactersopt
delimitato-doc-commento:
/** delimitato-commento-textopt */

c'è una preferenza? Ho notato una tendenza a preferire il formato a commento di una riga singola, ma non so se ci sono motivi tecnici o pratici oltre a quelli che scelgono da un punto di vista estetico.

Ho anche letto nel libro "C# per gli sviluppatori Java" di Jones e Freeman il seguente: commenti di documentazione

codice sono preceduti da tre barre, come illustrato di seguito:
/// A single line documentation comment.
Le specifiche C# consigliano anche l'uso del token familiare/** per identificare i commenti di documentazione multilinea. Tuttavia la versione 7.00 del compilatore C# non supporta questa sintassi.

Sono stato in grado di verificare che le ultime versioni del CSC non funzionano con la sintassi multilinea. Per quanto posso dire questa sintassi funziona bene.

**edit** Alcune persone hanno chiesto di mostrare un campione. Ecco l'esempio:

/// <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; 
} 

Quindi la domanda, ribadito, è che la forma è preferibile, ci sono ragioni tecniche o di altro per preferire la documentazione commento stile Method1 nel campione, al di sopra, o Method2 nel campione, sopra?

Answer 1

Info Sono stato in grado di raccogliere dal distacco a questa domanda conferma che, anche se csc /doc: accetterà entrambi i formati, il formato a linea singola ha alcuni vantaggi rispetto al formato multi-linea:

1) In Visual Studio IntelliSense ti fornirà informazioni che chiariscono gli argomenti che stai trasmettendo in un'espressione di chiamata di metodo mentre stai digitando, indipendentemente dal fatto che tu abbia originariamente documentato il tuo metodo con /// o/**. Tuttavia, Visual Studio ti fornirà il supporto per scrivere i commenti della documentazione usando i prefill solo se utilizzi il formato ///. Ad esempio, se si posiziona il cursore sopra di una dichiarazione di metodo in Visual Studio e preme / tre volte si vedrà un modello specifico contesto generato per voi in questo modo:

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

Questo non funziona se posizioni il cursore sul metodo e premi /, *, *.

2) Il formato a riga singola consente un layout più pulito dei commenti della documentazione poiché ogni riga inizia con la stessa rientranza, tutte le linee del blocco possono essere utilizzate e ogni riga di informazioni di commento è allineata a sinistra.

3) In generale, i vantaggi dell'utilizzo dello stile a linea singola in quei commenti a riga singola sono liberi di contenere il */token mentre i commenti su più righe non lo sono; e in genere sono più facili da utilizzare se si copiano o incollano parti di commenti da un posto a un altro all'interno di un editor.

4) Esiste anche la prova che il compilatore C# favorisce il formato a riga singola, se si considera come csc.exe gestisce i blocchi di documentazione adiacenti. Prendere in considerazione una dichiarazione come questa:

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

Quando passando per csc/doc: la documentazione verrà generato come se il contenuto di entrambi i blocchi modificati il ​​metodo principale. Questo comportamento non è intuitivo, ma diventa intuitivo se si trasformano i due righe di commento blocchi adiacente in due gruppi adjoined di commenti a riga singola, come segue:

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

Answer 2

Non ho mai incontrato alcuna limitazione quando si utilizza asterischi sopra le doppie (o triple) barre. Per qualsiasi ragione, la comunità C# ha deciso di usare doppie barre per i commenti.

È interessante notare che i commenti a doppia barra sono derivati ​​da C++ e Java. Di seguito ho incluso un elenco di lingue e ciò che denota un commento nella lingua:

1. ALGOL 60 -; (punto e virgola)
2. Lingue di assieme -; (Punto e virgola)
3. Ada, mySQL - - (due trattini)
4. C++/Java - // (due barre)
5. FORTRAN 90 -! (Punto esclamativo)
6. Perl, TCL, UNIX Shell, mySQL - # (cancelletto)
7. Visual Basic .NET - '(apostrofo)

Di seguito sono esempio di strumenti che utilizzano le doppie barre come commenti a linea singola e doppia riga.

Visual Studio Evidenziare un blocco di codice e utilizzare le combinazioni di tasti Ctrl + K + C e il codice è commentata utilizzando le doppie barre singola linea.

Santo Doc Ghost Doc è uno strumento che genera automaticamente la documentazione per il metodo. Usa la notazione della tripla barra. È a mia conoscenza che la tripla barra con l'uso di elementi XML nei commenti consente agli strumenti come NDoc e Sandcastle di generare il formato della Guida HTML in stile MSDN.

Atomineer Pro Atomineer Pro è un altro strumento che genera la documentazione livello di metodo dal nome del metodo e nomi dei parametri. Inoltre, ha usato la notazione tripla barra per impostazione predefinita.

MSDN C# norme di codifica La C# coding standards dire di utilizzare il doppia barra, e di non utilizzare i commenti a blocchi.

iDesign C# norme di codifica Mentre iDesign non è Microsoft, ho sempre sentito che erano un po 'di autorità nella comunità C#. Hanno pubblicato un documento C# Coding Standard che afferma che la doppia notazione è il metodo preferito.