Dove inserire commenti, dichiarazione di classe o costruttore?

2

Per una determinata classe, dove dovrebbero andare i commenti sullo scopo della classe?

/// <summary>
///       <----------------- describe the class here (1)?
/// </summary>
public class Message
{
  ...
  //class members here
  ...
  /// <summary>
  ///      <--------------- or here (2)?
  /// </summary>
  public Message()
  {
  }
}

Se vado con la prima opzione, lo scopo della classe è molto facile da trovare quando apro il file, è nello stesso posto, approssimativamente sulla stessa riga. Quando hai molte classi, questo è più facile per gli occhi. Non devi scorrere verso il basso oltre i membri per trovare il costruttore

Se vado con la seconda opzione, ottengo Intellisense quando creo un oggetto della classe, affermando il suo scopo e spiegando i parametri, che è molto bello.

Da quello che posso dire, non posso ottenere entrambi i vantaggi usando un solo metodo. L'unica soluzione che riesco a pensare è mettere lo stesso commento in entrambi i posti, ma sono solo informazioni duplicate e non mi piace.

    
posta mihai 20.02.2014 - 12:39
fonte

2 risposte

11

Lo scopo della classe dovrebbe essere descritto sopra il nome della classe.

Una documentazione sopra il costruttore è per documentare le differenze tra i diversi costruttori della classe e quali sono i parametri passati al costruttore o ai costruttori.

    
risposta data 20.02.2014 - 13:32
fonte
0

Posizione di avvocato di un piccolo diavolo:

Nessuna posizione.

Il nome della classe dovrebbe dire al lettore il suo scopo. In caso contrario, trova un nome migliore.

    
risposta data 20.02.2014 - 15:39
fonte

Leggi altre domande sui tag