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

Puoi dedurre uno da un altro, ma queste due sezioni rimangono separate, perché aiuta a focalizzarsi su quello che interessa alla persona durante la revisione / l'uso del 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, e questo è tutto ciò che mi interessa.

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

Ancora una volta, in questo esempio, puoi dedurre il sommario da <returns/> e inferire il valore di ritorno previsto dal sommario. Ma portando lo stesso argomento all'estremo, in questo caso non è necessario documentare il tuo metodo : il nome del metodo, messo dentro List<T> , con Predicate<T> match come argomento unico è piuttosto esplicito.

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

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

Collegamenti a MSDN: <summary> . <returns>

Why would you ever need to document returns separately from summary?

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

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

Inserisco alcune osservazioni che un chiamante dovrebbe sapere che non sono ovvie dal nome del metodo e dai parametri (e dai loro nomi). Speriamo comunque che il nome e i parametri del metodo rendano abbastanza ovvio che il commento può essere molto breve.

Sono stato lacerato dalla stessa domanda filosofica ultimamente 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 è fatto internamente, ma cita a) perché il chiamante vorrebbe chiamare questo metodo, b) quali sarebbero i risultati attesi di chiamare il metodo. Se è necessario documentare come funziona il metodo, lo metto nel corpo del codice stesso.
• Se un metodo ha una complessità sufficiente, la descrizione generale e una sezione separata [restituzioni] sembrano essere giustificate. Non vuoi che il lettore legga l'intera descrizione e cerchi di dedurre come interpretare il valore di ritorno.
• Se il metodo è così semplice che il modo migliore per descrivere quello che fa è dire qualcosa come "Questo metodo restituisce l'indirizzo di una persona", allora salta la sezione [restituisce] in quanto l'aggiunta sembrerebbe andare contro il principio DRY e Sono un grande sostenitore di ciò. Molti metodi di accesso one-liner sembrano rientrare in questa categoria.

Il sommario dovrebbe essere il più descrittivo che potrebbe essere 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. Ridefiniamo il tuo esempio:

true if the List contains one or more elements that match the conditions defined by the specified predicate; otherwise, false.

diventa

true if any element of List matches predicate; otherwise false.