Selon les commentaires que je reçois, je pourrais soulever cette "norme" avec mes collègues. Cela pourrait devenir une règle personnalisée de stylécop. Y a-t-il un écrit déjà?
SO, STYLECOP le dicte déjà pour Pensez-vous qu'il est logique de demander la même chose des commentaires? sur la note connexe: Si un commentaire est déjà long, il devrait-il être écrit comme une phrase appropriée? Par exemple (peut-être que j'ai essayé trop d'illustrer un mauvais commentaire): vs. si figuré - la plupart du temps, si l'on dérange d'écrire un commentaire, il pourrait aussi aussi être informatif. Considérez ces deux échantillons: et sans doute, on n'a pas besoin d'un commentaire du tout, mais depuis un est fourni, je penserais que le second est meilleur. Veuillez sauvegarder votre opinion. Avez-vous une bonne référence pour l'art de commenter, en particulier s'il s'agit de .net? Merci. Résumé , param et retour Tags de la documentation.
5 Réponses :
Prendre le temps d'écrire des commentaires clairs, lisibles et compréhensibles n'est jamais gaspillé. Combien de fois ai-je réaffirmé mes propres commentaires à une date ultérieure que pour la lutte pour les comprendre. Les personnes qui écrivent des commentaires bâclés ou mal formés appuyent souvent les mêmes traits de leur code.
Si le code a besoin d'un commentaire, il devrait être bien formé, car l'OMI est probablement un concept (non trivial) qui a besoin d'expliquer.
Les commentaires triviaux tels que dans vos exemples doivent être évités. Ils n'ajoutent que du bruit.
J'écris souvent des commentaires qui sont simplement destinés à m'aider à trouver des sections de code. (J'utilise aussi des régions pour cela.) Par exemple:
Parce que l'IDE colorise des commentaires, il rend parfois pratique d'avoir des commentaires courts comme celui-ci aider à bloquer mentalement les choses dans des segments. Je fais habituellement cela pour seulement une douzaine de lignes de code ou deux. Si c'est plus long, alors un I Écrivez aussi souvent des notes dans mes commentaires, parfois comme référence pour moi comme ceci: Ce n'est pas une phrase grammaticalement belle ou complète, mais cela a du sens. où j'ai tendance à utiliser des phrases plus complètes et structurées se situe dans le résumé de mes méthodes, comme celle-ci: ceux que je ressens est plus susceptible d'être lu par Quelqu'un d'autre et cela aide à avoir la verbosité et la mise en forme propre. // serveur #region semble mieux. // Remarque: -273.15 est un zéro absolu dans  ° C, utilisé pour une mintaille inférieure à
+1 pour le bit résumé, c'est assez agréable. Certains de mes collègues configurent Resharper pour dépasser tous les commentaires "traditionnels".
Sûr! C'est juste Alt + 176. Je traite avec ce symbole un lot dans mon travail! :)
Remarque: -273.15 est un zéro absolu en ° C, utilisé pour une mintaille ci-dessous. - C'est presque une bonne phrase, il suffit de gifler une «s'il vous plaît» devant elle. C'est ce que j'essayais. Oui, je peux voir comment "// serveur" ou "// constructeurs" sont utiles. Je suppose que la question est à nouveau - si un commentaire est déjà long, alors cela devrait-il être une phrase appropriée?
Je pense que ma réponse officielle serait "non", car il n'y a pas de véritable raison autre que si vous êtes plus à l'aise avec des notes de langue anglaises (ou autres). Aucune police de grammaire ne va vérifier les commentaires. La seule raison pour laquelle il pourrait avoir d'importance est que si vous êtes dans un environnement de développement de l'équipe et que vos collègues insistent pour que vous amélioriez la lisibilité de vos commentaires. :)
Oui, je suis dans un environnement d'équipe et j'aimerais voir de meilleurs commentaires :)
Ensuite, vous avez votre réponse! :)
Si vous commencez des méthodes dans Visual Studio, vous devez envisager d'utiliser le résumé et les paramètres en haut de la méthode. De cette façon, vous avez des détails sur la méthode pendant le code complet. Voici un exemple
Critant la optique "Donc, Styecop le dicte déjà pour les étiquettes de documentation Résumé, param et retour" ...
J'ai constaté que lorsque j'essaie d'être bref avec des commentaires (c'est-à-dire des phrases incomplètes, des fragments), je laissais souvent des hypothèses clés ou des mots qui clarifieraient en réalité le sens. J'ai du mal à trouver un exemple concret pour le moment, désolé.
En général, cependant, vous forçant à écrire des phrases complètes et appropriées vous oblige également à réfléchir davantage à ce que vous essayez vraiment de dire avec le commentaire. Je me suis souvent pris pour repenser ce que je veux vraiment inclure dans un commentaire en écrivant intégralement.
Il n'y a pas de bonne raison de sacrifier la clarté à l'autel de la brièveté. Quelqu'un aura besoin de comprendre le code à l'avenir. Les commentaires sont pour eux, donc les rendre faciles à grok.
Personnellement, je mettrais ce type de commentaires dans le bloc de code à l'intérieur du cas échéant, vous pouvez avoir un commentaire pour la condition d'autre si on existe.