Le terrain doit avoir une documentation en-tête de Style Cop - odeur de Code?

Je viens de style de course, cop contre une partie de mon code et a obtenu quelques-uns:

SA1600: The field must have a documentation header.

Maintenant, ne vous méprenez pas, j'aime le style de la cop, c'est génial quand vous travaillez sur un projet avec plus d'une personne, mais cette règle semble un peu excessif pour moi. Pourquoi voudriez-vous ajouter:

    ///<summary>
    ///blah blah blah
    ///</summary>

en haut de chaque variable. Je suis assez sûr que je me souviens de quelqu'un en disant(Martin Fowler, Kent Beck..ne peux pas vraiment me rappeler ATM) que le commentaire devrait dire "pourquoi" et non "ce" et je ne peux vraiment pas voir comment vous pouvez expliquer pourquoi sur une variable.

J'ai aussi trouver le code qui a des commentaires sur chaque variable la plus difficile à lire parce que tout ce que vous voyez est des peluches.

Mes pensées sont si vous avez d'expliquer ce que chaque variable est alors vous êtes vraiment à défaut en termes de nommage.

Personne d'autre ne trouver en commentant des variables un peu une odeur de code ou est-ce juste moi.

Bob Martin dit que "les Commentaires sont toujours échecs" (emp. ajoutée) -CC, Ch 4, p. 54. Donc, étant donné que ce StyleCop règle exige des commentaires dans tous ces endroits, tout le temps (en supposant que vous travaillez tous vos mises en garde, et vous devriez parce qu'ils sont là pour vous aider à écrire du bon code), cette règle n'est pas valide comme par Oncle Bob. Si un commentaire, qui est un mal nécessaire, et sur l ' occassion rare, devient nécessaire, vous que le développeur saura, de sorte que vous allez ajouter. Dans ce cas, les règles sur le format xml sont une bonne chose, alors je l'ai gardé toutes les règles sauf 1600-02, 1611, 1615, 1618 à atténuer certains problèmes qu'il mentionne.

OriginalL'auteur Nathan W | 2009-07-07