Commentaires C # sur la fermeture {}

Question

Je travaille un peu avec DevExpress CodeRush et Refactor! Pro cette semaine, et j’ai choisi un plug-in de commentaire qui générera automatiquement des commentaires lorsque vous tapez du code.

Je ne veux pas parler de la qualité de son travail de définition du sens de base (plutôt bon, en fait), mais sa mise en œuvre par défaut soulève une question.

Par défaut, si vous tapez un caractère} pour fermer un bloc, le plug-in ajoutera un commentaire comme celui-ci ...

using(MyType myType = new MyType())
{
    myType.doWork();
} // using

(c’est-à-dire ajouter un commentaire à l’attribut de fermeture qui l’a ouvert.)

Bien que je puisse constater qu'il existe des cas où ce comportement peut être très utile, j'estime que le code résultant semble très désordonné avec tous les commentaires supplémentaires.

Je me demandais ce que les autres personnes pensent de ce genre de commentaire. Pas seulement d'un point de vue académique, mais si je reçois un bon nombre de commentaires négatifs à leur sujet, je peux décider de les infliger à mes collègues ou de les en éliminer.

Answer 1

Je pense que de tels commentaires sont inutiles, à moins que le code soit affreux. Avec un formatage correct du code, il n’est pas difficile de voir où commence un bloc et où s’achève un bloc, car ces blocs sont généralement en retrait.

Modifier: Si une procédure est tellement volumineuse que le bloc de code fermé par une accolade n'est pas clairement visible, il devrait déjà y avoir déjà des commentaires plus descriptifs décrivant la procédure de toute façon et ces commentaires ne seraient que fouillis.

Answer 2

Je trouve l'idée d'un plugin qui génère des commentaires à partir de code plutôt inutile. Si cela peut être déduit par la machine, il peut également l'être par quiconque le lira. Les commentaires risquent fort d'être totalement redondants.

Je pense que le commentaire d'accolade fermant est désordonné. Il fournit des informations qui sont mieux fournies directement par l'EDI si l'individu le souhaite.

Answer 3

Tous les commentaires décrivant ce que le code vous dit déjà sont inutiles.

Si vous avez vraiment des blocs de code si longs qu'il vous faut beaucoup défiler pour commencer, vous avez commis une erreur et vous pouvez envisager de scinder le code.

Answer 4

Style de commentaire incorrect - il introduit une surcharge de maintenance dans la base de code.

J'ai déjà rencontré des codeurs ex-VB qui trouvaient confuses les traces de } dans le code de syntaxe C, mais dans ce scénario, le vrai correctif consiste à refactoriser votre code pour éviter une imbrication profonde et fonctions et / ou blocs de code excessivement longs.

Answer 5

Peut-être utile si le bloc using s'étend sur une page de l'EDI, mais vous devez vous préoccuper d'autres problèmes. Dans ce cas, je me débrouille avec une mise en retrait appropriée et un IDE qui met en évidence l'accolade correspondante lorsque j'en sélectionne un.

Je lui donne un coup de pouce en général, mais avec une utilisation potentielle lorsque vous ne pouvez pas éviter un bloc long autrement.

Answer 6

Parfois, vous obtenez des blocs de code très volumineux ou de nombreux blocs imbriqués qui se ferment ensemble. J'utilise parfois ce style dans des cas comme celui-ci, mais certainement pas tout le temps. Je ne le restreins pas non plus au code: le format HTML peut grandement profiter de ce style de "commentaires rapprochés":

<div id="content">
    <div id="columns">
        <div class="column">

            <!-- .. snip a lot of lines .. -->

        </div> <!-- .column -->
    </div> <!-- #columns -->
</div> <!-- #content -->

Answer 7

Ce type de commentaires ne sont utiles que sur de très longs blocs de code contenant de nombreux blocs imbriqués. Mais cela dit, cela ne devrait pas être le cas en premier lieu car de nombreux blocs imbriqués et de longues méthodes appellent à la refactorisation. Donc, je n'aime pas du tout cela, car le lecteur peut évidemment voir de quel bloc de code il s'agit.

Answer 8

Je pense qu'il serait plus utile que les commentaires d'utiliser une fonctionnalité de l'EDI non seulement pour mettre en surbrillance les paires d'accolades correspondantes, mais également pour afficher la ligne d'ouverture dans une info-bulle. Ainsi, si vous survolez l'accolade fermante dans votre exemple, elle apparaîtra. " using (MyType myType = new MyType ()) " dans une info-bulle.

Cela vous permettrait de comprendre facilement les accolades imbriquées complexes pour les grandes fonctions sans générer de fouillis visuel constant.

Answer 9

Je trouve toujours utile de se souvenir de ça ...

Un code clair et bien écrit fournira une explication suffisante de ce que le code permet à un programmeur compétent de le récupérer.

Les commentaires doivent rester dans le code pour expliquer pourquoi le code le fait!

En d'autres termes, utilisez des commentaires pour aider le lecteur de votre code à comprendre l'algorithme, ou ce que le code est censé atteindre , et non comment il y parvient!

Vous voudrez peut-être consulter ce message de Jeff Atwood .

Answer 10

Ne le faites pas, il ajoute simplement du bruit s'il est utilisé partout. Outre l'indentation appropriée, il devrait résoudre le problème de lisibilité.

Answer 11

Je le garderais éteint. Je vois seulement un intérêt à utiliser ceci lorsque plusieurs blocs se terminant au même endroit (blocs plus longs ou plus courts) - je les ai moi-même utilisés dans certains cas comme ceux-ci. Toutefois, s’ils sont utilisés, il est préférable de les ajouter manuellement, dans des endroits choisis avec soin, plutôt que de les ajouter à un outil automatisé.

Answer 12

Si vous devez déterminer si un certain type de commentaire est utilisable ou non, c'est probablement ce dernier.

Les commentaires servent à expliquer certains blocs de code ou une entité dans son ensemble, afin de faciliter la compréhension; ne pas rendre la mise en forme plus facile à lire.

Avoir un plugin toujours conforme à ce comportement est à la fois obèse et moche.

Answer 13

Je conviens qu'il existe de bien meilleurs moyens de décrire le code.

Si vous avez un long corps de code précédé d'un seul commentaire informatif tel que // Fix Work Item, vous pouvez prendre ce code et le refactoriser comme sa propre méthode. Utilisez ensuite le commentaire comme nom de la nouvelle méthode, FixWorkItem (). Cette opération est un moyen rapide de rendre votre code plus auto-documenté et peut même révéler certaines caractéristiques de conception que vous n'aviez pas remarquées auparavant.

Gardez un œil sur les commentaires uniques comme ceux-ci en tant que refacteurs potentiels, qui peuvent être gérés automatiquement par l'EDI. Le code qui se documente est meilleur que même les commentaires autonomes les mieux écrits, sauf bien sûr pour décrire l’intention.