Un commentaire de méthode doit-il inclure à la fois un résumé et une description de retour alors qu'ils sont souvent si similaires?

Je suis un partisan du code correctement documenté, et je suis bien conscient des inconvénients possibles de celui-ci . Cela sort du cadre de cette question.

J'aime suivre la règle consistant à ajouter des commentaires XML pour chaque membre public, compte tenu de mon intérêt pour IntelliSense dans Visual Studio.

Il existe cependant une forme de redondance qui dérange même un commentateur excessif comme moi. À titre d'exemple, prenez 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 )
{
    ...
}

Summaryet returnsdisent essentiellement la même chose. Je finis souvent par écrire le résumé plus d'un returnspoint de vue, en abandonnant returnscomplètement la documentation.

Renvoie true lorsque la liste contient des éléments qui correspondent aux conditions définies par le prédicat spécifié, false dans le cas contraire.

De plus, la documentation des retours n'apparaît pas dans IntelliSense, donc j'écris plutôt toute information immédiatement pertinente dans summary.

1. Pourquoi auriez-vous besoin de documenter returnsséparément summary?
2. Des informations sur les raisons pour lesquelles Microsoft a adopté cette norme?

Vous pouvez en déduire l'une de l'autre, mais ces deux sections restent distinctes, car cela permet de se concentrer sur celle qui intéresse la personne lors de la révision / utilisation du code .

En prenant votre exemple, je préfère écrire:

/// <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)
{
    ...
}

• Si je revois ce code et que je veux savoir ce que fait la méthode, j'ai lu le résumé, et c'est tout ce qui m'importe.

• Maintenant, imaginons que j'utilise votre méthode et la valeur de retour que je reçois est étrange, étant donné l'entrée. Maintenant, je ne veux pas vraiment savoir ce que fait la méthode, mais je veux en savoir plus sur la valeur de retour. Ici, la <returns/>section aide et je n'ai pas besoin de lire le résumé.

Encore une fois, dans cet exemple, vous pouvez déduire le résumé de <returns/>, et déduire la valeur de retour attendue du résumé. Mais en poussant le même argument à l'extrême, il n'est pas du tout nécessaire de documenter votre méthode dans ce cas: le nom de la méthode, mis à l'intérieur List<T>, avec Predicate<T> matchcomme seul argument est tout à fait explicite.

N'oubliez pas que le code source est écrit une fois mais lu de nombreuses fois . Si vous pouvez réduire l'accise pour les autres lecteurs de votre code, tout en passant dix secondes à écrire une phrase supplémentaire dans la documentation XML, faites-le.

Mon utilisation:
<summary>décrit ce que fait la méthode (pour obtenir le <returns>).
<returns>décrit la valeur de retour .

Liens vers MSDN: <summary>.<returns>

Pourquoi auriez-vous besoin de documenter les déclarations séparément du résumé?

Je pense que si la partie résumée est vraiment longue et descriptive, il pourrait être utile d'avoir à la fin une partie séparée et brève.

J'écris habituellement juste la <summary>partie dans mon propre code, en la formulant comme vous l'avez dit en disant "Renvoie _ ".

Je mets dans toutes les remarques qu'un appelant devrait savoir qui ne sont pas évidentes d'après le nom et les paramètres de la méthode (et leurs noms). Heureusement, le nom et les paramètres de la méthode rendent suffisamment évident le fait que le commentaire peut être très bref.

J'ai été déchiré par la même question philosophique ces derniers temps et je ne sais toujours pas ce qu'est une bonne solution. Mais jusqu'à présent, c'est mon approche ...

• La documentation de la méthode ne décrit que ce que les appelants externes doivent savoir. Il ne parle pas de la façon dont ce travail est effectué en interne, mais mentionne a) pourquoi l'appelant voudrait appeler cette méthode, b) quels seraient les résultats attendus de l'appel de la méthode. S'il est nécessaire de documenter le fonctionnement de la méthode, je le mets dans le corps du code lui-même.
• Si une méthode est suffisamment complexe, alors une description générale et une section [retours] séparée semblent être justifiées. Vous ne voulez pas que le lecteur lise la description complète et tente de déduire comment interpréter la valeur de retour.
• Si la méthode est si simple que la meilleure façon de décrire ce qu'elle fait est de dire quelque chose comme "Cette méthode renvoie l'adresse de la personne", alors je saute la section [retours] car l'ajout semblerait aller à l'encontre du principe DRY et je suis un grand défenseur de cela. Beaucoup de méthodes d'accessoires à une ligne semblent entrer dans cette catégorie.

Le résumé doit être aussi descriptif qu'il pourrait être utile; la description des paramètres et de la valeur de retour doit être courte et douce. Si vous avez le choix entre un mot et cinq, utilisez-en un. Resserrons votre exemple:

true si la liste contient un ou plusieurs éléments qui correspondent aux conditions définies par le prédicat spécifié; sinon, faux.

devient

true si un élément de List correspond au prédicat; sinon faux.