Un commento di metodo dovrebbe includere sia un sommario che una descrizione di ritorno quando sono spesso così simili?

Sono un sostenitore del codice adeguatamente documentato e sono ben consapevole dei possibili aspetti negativi di esso . Questo è al di fuori dell'ambito di questa domanda.

Mi piace seguire la regola di aggiungere commenti XML per ogni membro pubblico, considerando quanto mi piace IntelliSense in Visual Studio.

Esiste tuttavia una forma di ridondanza, a cui anche un commentatore eccessivo come me è infastidito. Ad esempio prendi List.Exists () .

/// <summary>
///     Determines whether the List<T> contains elements
///     that match the conditions defined by the specified predicate.
/// </summary>
/// <returns>
///     true if the List<T> contains one or more elements that match the
///     conditions defined by the specified predicate; otherwise, false.
/// </returns>
public bool Exists( Predicate<T> match )
{
    ...
}

Summarye returnssostanzialmente dicono la stessa cosa. Spesso finisco per scrivere il sommario più da una returnsprospettiva, lasciando cadere completamente la returnsdocumentazione.

Restituisce vero quando l'elenco contiene elementi che corrispondono alle condizioni definite dal predicato specificato, falso altrimenti.

Inoltre, la documentazione di restituzione non viene visualizzata in IntelliSense, quindi preferisco scrivere qualsiasi informazione immediatamente rilevante in summary.

1. Perché mai dovresti documentare returnsseparatamente summary?
2. Qualche informazione sul perché Microsoft ha adottato questo standard?

Puoi dedurne uno dall'altro, ma quelle due sezioni rimangono separate, perché aiuta a concentrarsi su quello che interessa alla persona quando rivede / utilizza il codice .

Prendendo il tuo esempio, preferirei scrivere:

/// <summary>
/// Determines whether the List<T> contains elements that match the conditions
/// defined by the specified predicate.
/// </summary>
/// <returns>
/// A value indicating whether at least one element matched the predicate.
/// </returns>
public bool Exists(Predicate<T> match)
{
    ...
}

• Se sto rivedendo questo codice e voglio sapere cosa fa il metodo, leggo il sommario, ed è tutto ciò che mi interessa.

• Ora, immaginiamo che sto usando il tuo metodo e il valore restituito che ricevo è strano, dato l'input. Ora, non voglio davvero sapere cosa fa il metodo, ma voglio sapere qualcosa di più sul valore di ritorno. Qui, la <returns/>sezione aiuta e non ho bisogno di leggere il riassunto.

Ancora una volta, in questo esempio, è possibile inferire il riepilogo <returns/>e dedurre il valore di ritorno atteso dal riepilogo. Ma portando lo stesso argomento all'estremo, non è necessario documentare affatto il tuo metodo in questo caso: il nome del metodo, messo dentro List<T>, con Predicate<T> matchcome unico argomento è abbastanza esplicito.

Ricorda, il codice sorgente viene scritto una volta ma letto molte volte . Se riesci a ridurre le accise per gli ulteriori lettori del tuo codice, trascorrendo dieci secondi a scrivere una frase aggiuntiva nella documentazione XML, fallo.

Il mio utilizzo:
<summary>descrive cosa fa il metodo (per ottenere il <returns>).
<returns>descrive il valore di ritorno .

Link a MSDN: <summary>.<returns>

Perché mai dovresti documentare i resi separatamente dal riepilogo?

Penso che se la parte di riepilogo è davvero lunga e descrittiva, potrebbe essere utile avere una parte di restituzione breve e separata alla fine.

Di solito scrivo solo la <summary>parte nel mio codice, formulandola nel modo in cui hai detto "Restituisce _ ".

Ho inserito alcune osservazioni che un chiamante dovrebbe sapere che non sono evidenti dal nome e dai parametri del metodo (e dai loro nomi). Eventualmente, il nome e i parametri del metodo rendono abbastanza ovvio che il commento può essere molto breve.

Ultimamente sono stato strappato dalla stessa domanda filosofica e non sono ancora sicuro di quale sia una buona soluzione. Ma finora, questo è stato il mio approccio ...

• La documentazione del metodo descrive solo ciò che i chiamanti esterni devono sapere. Non parla di come questo lavoro viene svolto internamente, ma menziona a) perché il chiamante vorrebbe chiamare questo metodo, b) quali sarebbero i risultati attesi dalla chiamata del metodo. Se è necessario documentare il funzionamento del metodo, lo inserisco nel corpo del codice stesso.
• Se un metodo ha una complessità sufficiente, allora la descrizione generale e una sezione separata [resi] sembrano essere giustificate. Non vuoi che il lettore legga l'intera descrizione e cerchi di dedurre come interpretare il valore restituito.
• Se il metodo è così semplice che il modo migliore per descrivere ciò che fa è dire qualcosa come "Questo metodo restituisce l'indirizzo della persona", allora salto la sezione [restituisce] poiché l'aggiunta sembra andare contro il principio DRY e sono un grande sostenitore di ciò. Molti metodi di accesso one-liner sembrano rientrare in questa categoria.

La sintesi dovrebbe essere tanto descrittiva quanto utile; le descrizioni dei parametri e il valore di ritorno dovrebbero essere brevi e dolci. Se hai una scelta tra una parola e cinque, usane una. Rafforziamo il tuo esempio:

vero se l'elenco contiene uno o più elementi che corrispondono alle condizioni definite dal predicato specificato; altrimenti, falso.

diventa

vero se qualsiasi elemento dell'elenco corrisponde al predicato; altrimenti falso.