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 )
{
...
}
Summary
e returns
estão basicamente dizendo a mesma coisa. Costumo escrever o resumo mais de uma returns
perspectiva, descartando a returns
documentaçã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
.
- Por que você precisaria documentar
returns
separadamentesummary
? - Alguma informação sobre por que a Microsoft adotou esse padrão?
fonte
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>
fonte
summary
estado msdn descreve 'o que o método faz'. Votei até que você reserve um tempo para atualizar sua resposta para esclarecer a diferença entre o que o msdn afirma e o que você o formula. ; ptrue
se o predicado corresponder". Se alguém precisar saber o que constitui uma correspondência, poderá ler o restante da documentação.<summary>
e um,<returns>
faça isso". Como disse Blrfl, essa é apenas uma diretriz que podemos ou não querer usar.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.
fonte
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 ...
fonte
returns
. Percebo também que eles sempre usam a mesma formulação, por exemplo, "verdadeiro se ...; caso contrário, falso " para valores de retorno booleano. Gostaria de saber se eles também especificaram uma convenção para isso.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:
torna-se
fonte
returns
da Microsoft é muito longo. Se deve fazer alguma coisa, é simplesmente garantir que true significa que corresponde e falso que não.