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.
OriginalL'auteur Nathan W | 2009-07-07
Vous devez vous connecter pour publier un commentaire.
Je ne dirais pas que commenter une variable est toujours une odeur de code (et il n'a pas l'air comme ça de ce que vous dites, soit). Je suis d'accord que des commentaires de chaque variable, chaque fois, est pour le moins excessif, et éventuellement indicatif de nommage pauvres. En fait, certains diront que tout commentaire est une odeur de code, et que les noms descriptifs et court routines sont plus lisibles et éviter la situation où le code a été changé, mais les commentaires n'ont pas été mis à jour (qui a certainement me piquer dans quelques héritage des bases de code). Je ne pense pas que je prendrais très loin, mais si vous pouvez écrire du code qui est auto-explicatif, sans explication, qui ne semblent préférables.
Donc ouais, en gros ce que vous avez dit.
Ce que vous pensez est auto commentant est très différente de ce que j'ai, le gars qui arrive et lit votre code de six mois à partir de maintenant, va tenir compte de l'auto-commenter. Et si le commentaire ne correspond pas au code, puis de résoudre le commentaire.
OriginalL'auteur John Hyland
C'est tout à fait un vieux post, mais il est venu à travers elle, tout en recherchant une solution à ce problème moi-même, si bien que je voudrais proposer une solution.
Si vous ouvrez votre Paramètres.StyleCop fichier dans l'éditeur de règles, sélectionnez la Règles en matière de Documents nœud, puis dans le paramètres Détaillés section sur le droit de sélectionner les Inclure des champs option. Maintenant, il ne vous sera plus nécessaire pour les champs d'un document.
Oui, pourquoi ne pas cliquer sur tous les éléments vous êtes en désaccord avec jusqu'à StyleCop est compatible avec le code que vous écrivez. Ce serait le plus simple de tous.
OriginalL'auteur Nixus
Commentaires XML sont légèrement différentes de celles des autres commentaires.
Si vous définissez les choses correctement, vous pouvez les faire apparaître dans l'outil de conseils dans Visual Studio ET les utiliser pour créer MSDN style de documentation avec de Château de Sable. Je pense qu'ils devraient vous dire ce que le truc est en train de faire lorsque vous n'avez pas accès au code source.
Le point est que ces commentaires peuvent apparaître sans le code source qu'ils sont les commentaires. Ils devraient être utiles à un autre devloper qui ne peuvent pas voir votre code et ne s'intéressent pas comment vous faites les choses.
Je ne sais pas à propos de la "Cop" de l'outil que vous utilisez, mais il serait agréable d'avoir un moyen de signalisation de l'outil à l'intention de laisser un param vide. Donc:
J'ai travaillé sur des projets où nous avons de tout remplir et nous obtenir des choses comme:
Si vous ne souhaitez pas utiliser les fonctions ci-dessus, aller de l'avant d'éteindre le Style de la Cop de la règle.
OriginalL'auteur jrcs3
Tout à fait d'accord, et la première chose que j'ai désactivé dans StyleCop. Si vous avez besoin de l'expliquer, vous avez nommé dans un mode qui a besoin d'explication et n'ont pas à faire le code auto-documentation.
OriginalL'auteur Troy Hunt
Pour ceux qui continuent à venir à travers cette question, ce post comment-changer-une-stylecop-règle fait a la réponse parfaite.
OriginalL'auteur Franky
Vous devriez essayer GhosDoc est un moyen facile d'avoir de la documentation automatisée pour chaque membre code de votre application. Il suffit de l'installer, cliquez-droit sur le membre et sélectionnez le document ce!
OriginalL'auteur Do.This
Je pense que la bonne réponse est "ça dépend". Vous pouvez certainement expliquer le "pourquoi" d'une variable étant marquée statique/const, ou la logique métier/restrictions sur la variable. Cela dit, je suis d'accord que le fait de voir chaque variable commentaire entrave la lisibilité et peut indiquer aveuglément à la suite d'une norme ou d'une mauvaise appellation.
OriginalL'auteur Andrew Coleson