Um comentário do método deve incluir um resumo e uma descrição do retorno, quando geralmente são tão semelhantes?

Sou um defensor do código devidamente documentado e estou ciente das possíveis desvantagens dele . Isso está fora do escopo desta questão.

Eu gosto de seguir a regra de adicionar comentários XML para cada membro público, considerando o quanto eu gosto do IntelliSense no Visual Studio.

Existe uma forma de redundância, no entanto, mesmo um comentarista excessivo como eu é incomodado. Como exemplo, considere 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 returnsestão basicamente dizendo a mesma coisa. Costumo escrever o resumo mais de uma returnsperspectiva, descartando a returnsdocumentação completamente.

Retorna true quando a Lista contém elementos que correspondem às condições definidas pelo predicado especificado, caso contrário, false.

Além disso, a documentação de devoluções não aparece no IntelliSense, portanto, escrevo qualquer informação imediatamente relevante em summary.

1. Por que você precisaria documentar returnsseparadamente summary?
2. Alguma informação sobre por que a Microsoft adotou esse padrão?

Você pode deduzir uma da outra, mas essas duas seções permanecem separadas, porque ajuda a focar na que interessa à pessoa ao revisar / usar o código .

Tomando seu exemplo, prefiro escrever:

/// <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 estou revisando esse código e quero saber o que o método faz, leio o resumo e é com isso que me interessa.

• Agora, vamos imaginar que estou usando seu método e o valor de retorno que recebo é estranho, considerando a entrada. Agora, eu realmente não quero saber o que o método faz, mas quero saber algo mais sobre o valor de retorno. Aqui, a <returns/>seção ajuda, e não preciso ler o resumo.

Novamente, neste exemplo, você pode inferir o resumo de <returns/>e inferir o valor de retorno esperado do resumo. Mas, levando o mesmo argumento ao extremo, não há necessidade de documentar seu método nesse caso: o nome do método, colocado dentro dele List<T>, com Predicate<T> matchum único argumento, é bastante explícito.

Lembre-se, o código fonte é escrito uma vez, mas é lido várias vezes . Se você puder reduzir o imposto para os leitores adicionais do seu código, gastando dez segundos escrevendo uma frase adicional na documentação XML, faça-o.

Meu uso:
<summary>descreve o que o método faz (para obter o <returns>).
<returns>descreve o valor de retorno .

Links para MSDN: <summary>.<returns>

Por que você precisaria documentar as devoluções separadamente do resumo?

Eu acho que se a parte do resumo for realmente longa e descritiva, pode ser útil ter uma parte separada e breve do retorno no final.

Normalmente, escrevo apenas a <summary>parte do meu código, redigindo-a da maneira como você dizia "Retorna _ ".

Fiz algumas observações que um chamador deve saber que não são óbvias a partir do nome do método e dos parâmetros (e seus nomes). Felizmente, porém, o nome e os parâmetros do método tornam óbvio o suficiente para que o comentário possa ser muito breve.

Ultimamente, tenho ficado com a mesma pergunta filosófica e ainda não tenho certeza do que é uma boa solução. Mas até agora, essa tem sido minha abordagem ...

• A documentação do método descreve apenas o que os chamadores externos precisam saber. Ele não fala sobre como esse trabalho é feito internamente, mas menciona a) por que o chamador gostaria de chamar esse método; b) quais seriam os resultados esperados de chamar o método. Se for necessário documentar como o método funciona, eu o coloco no próprio corpo do código.
• Se um método tem complexidade suficiente, a descrição geral e uma seção [retornos] separada parecem justificadas. Você não quer que o leitor leia a descrição inteira e tente inferir como interpretar o valor de retorno.
• Se o método é tão simples que a melhor maneira de descrever o que ele faz é dizer algo como "Este método retorna o endereço da pessoa", pulo a seção [Returns], pois a adição parece contrariar o princípio DRY e eu estou um grande defensor disso. Muitos métodos de acesso único de uma fila parecem se encaixar nessa categoria.

O resumo deve ser o mais descritivo possível; as descrições dos parâmetros e do valor de retorno devem ser breves e agradáveis. Se você tiver uma escolha entre uma palavra e cinco, use uma. Vamos reforçar seu exemplo:

true se a lista contiver um ou mais elementos que correspondam às condições definidas pelo predicado especificado; caso contrário, false.

torna-se

true se algum elemento da lista corresponder ao predicado; caso contrário, falso.