Quali sono le best practice per la documentazione del codice C # con commenti XML?

StackOverflow https://stackoverflow.com/questions/3143324

  •  01-10-2019
  •  | 
  •  

Domanda

che sto passando un po 'di nuovo codice appena scritto e l'aggiunta di commenti sytle NDoc ai miei classi e metodi. Spero di generare un documento abbastanza buono stile MSDN per riferimento.

In generale, quali sono alcune linee guida buoni quando si scrive commenti per una classe e di un metodo? Quali dovrebbero essere i commenti NDoc dire? Quello che non dovrebbero dire?

mi ritrovo a guardare a ciò che dicono i commenti .NET framework, ma che invecchia in fretta; se potessi avere alcune buone regole per guidare me stesso, ho potuto finire i miei documenti molto più veloce.

È stato utile?

Soluzione

Nei commenti utilizzati per la documentazione di compilazione API, è necessario:

  • Spiegare ciò che il metodo o proprietà non, perché esiste affatto, e spiegare qualsiasi concetto di dominio che non sono evidenti per il consumatore medio del codice.

  • Lista tutti i presupposti per i parametri (non può essere nullo, deve essere entro un certo intervallo, ecc.)

  • Lista qualsiasi post-condizioni che potrebbero influenzare il modo chiamanti che fare con i valori di ritorno.

  • Lista eccezioni il metodo può lanciare (e in quali circostanze).

  • Se esistono metodi simili, spiegare le differenze tra loro.

  • richiamare l'attenzione su qualcosa di inaspettato (ad esempio la modifica dello stato globale).

  • enumerano qualsiasi effetto collaterale, se ce ne sono.

Altri suggerimenti

Se si finisce con i commenti che non aggiungono alcun valore, sono solo uno spreco.

Ad esempio 

/// <summary>
/// Gets manager approval for an action
/// </summary>
/// <param name="action">An action object to get approval for</param>
public void GetManagerApprovalFor(Action action)

... si aggiunge assolutamente alcun valore e appena aggiunto più codice da mantenere.

Troppo spesso il codice è disseminato con questi commenti superflui.

StyleCop fornisce suggerimenti per il codice e stile commentando. I suggerimenti che dà sono in linea con lo stile documentazione MSDN.

Per quanto riguarda il contenuto del commento, dovrebbe dare all'utente del codice abbastanza informazioni su ciò che tipo di comportamento aspettarsi. Si deve anche rispondere alle potenziali domande l'utente potrebbe avere. Quindi cercate di usare il codice come qualcuno che non sa nulla del codice, o meglio ancora, chiedere a qualcun altro di farlo.

Per le proprietà, il tuo commento dovrebbe indicare se la proprietà è di sola lettura, scrittura o solo lettura scrittura. Se si guarda a tutta la documentazione ufficiale di MS, i commenti proprietà doc iniziano sempre con "Gets ...", "Ottiene o imposta ..." e (molto raramente, evitare di scrivere solo le proprietà di solito) "Imposta ..."

Non dimenticare che cosa è un XML valido. Ad esempio: 

/// <Summary>
/// Triggers an event if number of users > 1000
/// </Summary>

(Errore: XML valido).

Scrivo la

Commento per includere le informazioni vorrei sapere se ero quello che chiama la funzione (o un'istanza di quella classe).

I scrivere il Commento per includere le informazioni vorrei sapere se mi è stato affidato il compito di debug o migliorare quella funzione o classe. Nota: questo non sostituisce la necessità di buone commenti in linea. Ma a volte una panoramica generale del funzionamento interno della funzione / classe sono molto utili.

Come indicato sul MSDN pagina , si utilizza la documentazione XML commenti per generare automaticamente la documentazione, in modo che i responsabili senso se si sta scrivendo un'API e non vogliono lavorare il doppio sia a codice e la documentazione, con l'ulteriore vantaggio di tenerli in sincronia - ogni volta che si cambia il codice, si modifica i commenti appropriati e rigenerare la documentazione.

Compila con /doc e il compilatore cercherà tutti i tag XML nel codice sorgente e creare un file di documentazione XML, quindi utilizzare uno strumento come Sandcastle per generare la documentazione completa.

Una cosa su commenti è loro aggiornamento. Troppe persone alterano una funzione quindi non modificare il commento per riflettere la modifica.

Autorizzato sotto: CC-BY-SA insieme a attribuzione
Non affiliato a StackOverflow
scroll top