È necessario "Ottiene o imposta .." nella documentazione XML delle proprietà?

Naviga le tue risposte
18

Sto cercando una raccomandazione di best practice per i commenti XML in C #. Quando si crea una proprietà, sembra che la documentazione XML prevista abbia il seguente formato: 

/// <summary>
/// Gets or sets the ID the uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID {
    get;
    set;
}

Ma poiché la firma della proprietà indica già quali operazioni sono disponibili per i client esterni della classe (in questo caso è sia get che set ) Mi sembra che i commenti siano troppo chiacchieroni e che forse il seguente sarebbe sufficiente: 

/// <summary>
/// ID that uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID {
    get;
    set;
}

Microsoft usa il primo modulo così sembra che sia una convenzione implicita. Ma penso che il secondo sia migliore per le ragioni che ho affermato.

Comprendo che questa domanda è un adetto per essere contrassegnata come non costruttiva, ma la quantità di proprietà che si devono commentare è enorme e quindi credo che questa domanda abbia il diritto di essere qui.

Apprezzerò qualsiasi idea o link alle pratiche raccomandate ufficiali.

    
posta Tomas 28.03.2013 - 13:31
fonte

4 risposte

28

La firma può dire ad altri pezzi di codice quali operazioni sono disponibili; tuttavia, non vengono mostrati chiaramente al programmatore mentre sta lavorando e la documentazione XML è pensata per le persone da consumare e non da un compilatore.

Prendi questa classe per esempio: 

public class MyClass
{
    /// <summary>
    /// The first one
    /// </summary>
    public int GetOrSet { get; set; }

    /// <summary>
    /// The second one
    /// </summary>
    public int GetOnly { get; private set; }

    /// <summary>
    /// The last one
    /// </summary>
    public int SetOnly { set; private get; }
}

Quando l'intellisense viene tirato su per accedere a una di queste proprietà, non vi è alcuna indicazione su quali possano essere scritti, letti o entrambi:

Allostessomodo,quandovisualizziamoladocumentazione,nonnesiamodeltuttosicuri:

Come tale aggiungiamo gets or sets , gets , o sets per renderlo più facile sul programmatore durante la scrittura del codice. Certamente non sarebbe scritto un grande blocco di codice che legge ed elabora alcuni dati solo per scoprire che non è possibile riportare tali dati alla proprietà come previsto.

    
risposta data 28.03.2013 - 14:22
fonte
2

StyleCop utilizza la notazione Gets or Sets ... che applica con la regola SA1623 .

La pagina collegata elenca un altro caso che non hai elencato: 

/// <summary>
/// Gets a value indicating whether the item is enabled.
/// </summary>
public bool Enabled
{
    get { return this.enabled; }
}

L'altra opzione che elencherai sarebbe. 

/// <summary>
/// ID that uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID { get; set; }

vs 

/// <summary>
/// ID that uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID { get; }

Che non fornirebbe informazioni sul suggerimento Intellisense che la proprietà è di sola lettura, potresti anche creare una convenzione per questo caso, ma Gets ... , Gets or Sets... fa il lavoro in modo piacevole.

Ci sono anche altre varianti elencate nella regola StyleCop che sono chiare usando Gets or Sets... ma potrebbe non essere senza.

Anche quando si genera documentazione da qualcosa come Doxygen o Sandcastle la notazione completa documenterebbe meglio l'API (ad esempio).

    
risposta data 28.03.2013 - 13:45
fonte
2

L'unica volta che aggiungo informazioni su come ottenere e impostare una proprietà nei commenti XML è quando non si comporta come previsto (pubblico diretto get e set).

Se entrambi sono privati o se contengono logica aggiuntiva, li accenno, altrimenti documenterò semplicemente l'intento della proprietà.

    
risposta data 28.03.2013 - 14:21
fonte
1

Sarei più felice con la versione più dettagliata.

L'altro è come avere un commento di "contatore incrementale" dopo, beh, incrementando una variabile contatore.

È ovvio che c'è un Get and Set. Se tu avessi un setter privato, sarebbe ovvio come avresti la parola chiave privata.

I commenti dovrebbero aggiungere valore, non solo essere la versione di commento di ciò che effettivamente è il codice.

    
risposta data 28.03.2013 - 13:41
fonte

Leggi altre domande sui tag

In che modo Scrum può essere adattato all'impostazione di un volontario? L'aggiunta di punti premio o funzionalità di gioco al software sul posto di lavoro potrebbe essere considerata poco nella comunità di programmazione?