Pourquoi les /// blocs de commentaires sont-ils importants?

Quelqu'un a dit une fois que nous devrions préfixer toutes nos méthodes avec les /// <summary>blocs de commentaires (C #) mais n’a pas expliqué pourquoi.

J'ai commencé à les utiliser et j'ai constaté qu'ils m'ennuyaient un peu, alors j'ai cessé de les utiliser, sauf pour les bibliothèques et les méthodes statiques. Ils sont encombrants et j'oublie toujours de les mettre à jour.

Existe-t-il une bonne raison d'utiliser des /// <summary>blocs de commentaires dans votre code?

J'utilise normalement des //commentaires tout le temps, ce sont juste les /// <summary>blocs sur lesquels je m'interrogeais.

Utilisez-les autant que possible.

Oui, ce sont des commentaires spéciaux qui deviennent la documentation de la méthode. Le contenu des <summary>balises de paramètre, etc. générées apparaît en intellisense lorsque vous ou une autre personne s'apprête à appeler votre méthode. Ils peuvent essentiellement voir toute la documentation de votre méthode ou de votre classe sans avoir à consulter le fichier lui-même pour savoir ce qu’il fait (ou essayer de lire simplement la signature de la méthode et espérer que tout ira au mieux).

Oui, utilisez-les absolument pour tout ce que vous souhaitez conserver ou partager.

Utilisez-les également avec Sandcastle et Sandcastle Help File Builder , qui prennent la sortie XML et la transforment en une magnifique documentation de style MSDN.

Au dernier endroit où j'ai travaillé, nous avons reconstruit la documentation tous les soirs et l'avons hébergée en tant que page d'accueil interne. Les initiales de la compagnie étaient MF, donc c'était MFDN;)

Normalement, je produis simplement un fichier .chm, qui est facilement partagé.

Vous seriez surpris de voir à quel point vous êtes accro à tout documenter une fois que vous commencez à le voir au format MSDN!

Si votre norme de codage exige que vous utilisiez de tels commentaires (et qu'une norme de codage pour une API ou un framework puisse l'exiger), vous n'avez alors pas le choix, vous devez utiliser ces commentaires.

Sinon, envisagez sérieusement de ne pas utiliser de tels commentaires. Vous pouvez les éviter dans la plupart des cas en modifiant votre code comme suit:

    /// <summary>
    /// Checks if a user is authorized to access the resource
    /// </summary>
    public bool SecurityCheck( User user ) {

    }

à

    /// <summary>
    /// Checks if a user is authorized to access the resource
    /// </summary>
    public bool IsAuthorizedToAccessResource( User user ) {

    }

à

    public bool IsAuthorizedToAccessResource( User user ) {

    }

Votre nom de classe, méthode et propriété devrait être évident, alors si vous en avez besoin, c'est probablement une odeur.

Cependant, je recommanderais de les utiliser sur toutes les classes, méthodes et propriétés publiques dans une API, une bibliothèque, etc. pour les écrire.

Mais de toute façon, vous la coupez, la maintenez ou la supprimez.

Si vous vous rendez compte que vous devez sans cesse revenir en arrière et modifier vos commentaires pour les adapter au nouveau code, vous risquez de les avoir mal interprétés. L'élément summary doit contenir exactement cela - un résumé - le quoi et le pourquoi de la chose que vous résumez.

Décrire comment quelque chose fonctionne dans les commentaires est une violation de DRY. Si votre code n'est pas suffisamment descriptif, vous devriez peut-être revenir en arrière et refactoriser.

Oui, je les ai créés. [lors de la construction de nouveaux systèmes à partir de zéro]

Non, je n'ai jamais bénéficié d'eux. [lorsque vous travaillez sur des systèmes existants nécessitant une maintenance]

J'ai constaté que les commentaires "Résumé" finissent par ne plus être synchronisés avec le code. Et une fois que j'ai remarqué quelques commentaires qui se comportent mal, j'ai tendance à perdre confiance en tous les commentaires sur ce projet - vous ne savez jamais à qui faire confiance.

Oublier de faire quelque chose n'en fait pas une mauvaise idée. Oublier de mettre à jour une documentation est. Je les ai trouvées très utiles dans ma programmation et les personnes qui héritent de mon code sont reconnaissantes de les avoir.

C'est l'un des moyens les plus visibles de documenter votre code.

Il est difficile de trouver le code source pour lire la documentation en ligne ou de déterrer un document qui décrit le code. Si vous pouvez faire apparaître quelque chose d'utile par l'intelligence, les gens vous aimeront.

" Il doit être très utilisé, comme moi;) "

Je jouais avec des commentaires (///). Pour un cours, vous pouvez simplement faire un commentaire comme celui-ci.

namespace test
{
    /// <summary>
    /// Summary description for Calendar.
    /// </summary>
    public partial class DatePicker : System.Web.UI.Page
    {

Mais, pour une méthode, vous pouvez en ajouter davantage avec une description des paramètres et des types de retour.

/// <summary>
/// Assign selected cases to the participating users based on the filters and configurations
/// </summary>
/// <param name="noOfParticipants">No. of participants to the Table</param>
/// <param name="value">Value of the participant</param>
/// <returns>No Of Cases Assigned on successfull completion</returns>
public long AssignCasesToParticipatingUsers(int noOfParticipants,string value)
{

Vous pouvez utiliser un raccourci pour créer ce commentaire (///+Tab).

les utiliser sauf pour les bibliothèques

C'est le moment où ils sont utiles. Avec la génération de documentation XML activée et une référence à l’assemblage, sans son projet, affichera plus de détails dans intellisense.

Mais pour les internes du projet actuel, ils ne font que gêner.

Je les utilise, mais comme d'autres personnes l'ont dit, pas universellement. Pour les petites méthodes, elles peuvent facilement être plus volumineuses que le code qu'elles expliquent. Ils sont particulièrement utiles pour générer de la documentation pouvant être transmise aux nouveaux utilisateurs du système afin qu’ils puissent se référer à quelque chose tout en l’apprenant. Même si, en tant que programmeurs, nous pouvons généralement trouver le code qui convient, il est bon que les commentaires nous guident et agissent comme une béquille. S'il doit être écrit quelque part, le code est l'endroit où il est le plus susceptible de rester à jour (plus probable qu'un document Word flottant).

J'utilise l'équivalent en VB (car ils ne me laisseront pas utiliser C # - apparemment, c'est trop difficile ... sans commentaire.) Je les trouve très pratiques. La plupart du temps, j'attends que la procédure ou la fonction soit à peu près terminée avant de les insérer, ne serait-ce que pour éviter de devoir modifier les commentaires ou les faire "désynchronisés".

Je n'écris pas nécessairement un roman - juste la base, la description du paramètre et quelques remarques (généralement quand il se passe quelque chose "d’extraordinaire" là-dedans - solution de contournement ou autre merde que je préférerais ne pas avoir là-dedans pas de choix "pour l'instant".) (Ouais, je sais, que "pour l'instant" peut durer des années.)

Je suis gravement irrité par le code non commenté. Un consultant a écrit la version initiale de l’un de nos composants sans rien commenter et son choix de noms laisse à désirer ici et là. Il est parti depuis un an et nous sommes toujours en train de trier ses affaires (en plus de travailler sur nos propres affaires).