質問
私はDevExpress CodeRushとRefactorを少し使っています!今週はProで、コードを入力すると自動的にコメントを生成するコメントプラグインを選びました。
基本的な意味(実際にはかなり良い)を選択するのがどれほど良い仕事になりたいかは知りませんが、デフォルトの実装では疑問が生じます。
デフォルトでは、ブロックを閉じるために}文字を入力すると、プラグインは次のようなコメントを追加します...
using(MyType myType = new MyType())
{
myType.doWork();
} // using
(つまり、開いた場所にある閉じ括弧のラベルにコメントを追加します。)
この振る舞いが非常に役立つ場合があることはわかりますが、追加のコメントを追加すると、結果のコードは非常に乱雑に見えます。
私は他の人たちが何をしているのだろうと思っていました;この種のコメントはどうでしたか。学術的な観点からだけでなく、それらについて多くの否定的なコメントを受け取った場合、同僚にそれらを与えるか、それを取り除くかを決めることができます。
解決
もちろん、コードがひどいものでない限り、そのようなコメントは役に立たないと思います。コードを適切にフォーマットすれば、ブロックがどこで始まり、どこで終わるかを見るのは難しくありません。通常、これらのブロックはインデントされています。
編集: プロシージャが非常に大きく、ブレースで閉じられているコードブロックがすぐにわからない場合は、とにかくプロシージャを説明する説明的なコメントが既にあるはずであり、これらのコメントは混乱しているだけです。
他のヒント
コードからコメントを生成するプラグインのアイデアはかなり役に立たないと思います。マシンが推測できる場合は、それを読んでいる人が推測することもできます。コメントは完全に冗長になる可能性が非常に高いです。
これらの閉じ括弧コメントは乱雑で、個人が望むならIDEによって直接提供されるほうが良い情報を提供すると思います。
コードがすでにあなたに伝えていることを説明しているすべてのコメントは不要です。
本当に長いコードブロックがあり、そこからスクロールを開始する必要がある場合は、何か間違ったことをしているので、コードを分割することを検討してください。
悪いコメントスタイル-コードベースにメンテナンスオーバーヘッドが発生します。
C構文コードの}
の痕跡が混乱していることを発見した元VBコーダーを知っていましたが、このシナリオでの本当の修正は、深いネストと過度に長い関数および/またはコードブロック。
usingブロックがIDEのページにまたがっている場合に便利かもしれませんが、心配する他の問題があります。この場合、適切なインデントと、1つを選択したときに一致するブレースを強調表示するIDEでうまくいきます。
一般的にはお断りしますが、そうでなければ長いブロックを避けられない場合に使用する可能性があります。
非常に大きなコードブロック、または多数のネストされたブロックが一緒に閉じる場合があります。私はこのような場合にこのスタイルを使用することがありますが、常にそうではありません。私はそれをコードに制限しません:HTMLはこのスタイルの" close commenting"の恩恵を受けることができます:
<div id="content">
<div id="columns">
<div class="column">
<!-- .. snip a lot of lines .. -->
</div> <!-- .column -->
</div> <!-- #columns -->
</div> <!-- #content -->
この種のコメントは、ネストされたブロックが多数ある非常に長いコードブロックでのみ役立ちます。しかし、多くのネストされたブロックと長いメソッドがリファクタリングを必要とするため、そもそもそうではないはずです。 読者は明らかにそれがどのコードブロックであるかを見ることができるので、私はこれがまったく好きではありません。
コメントよりも有用なのは、一致する中括弧のペアを強調表示するだけでなく、ツールチップに開始線を表示するIDE機能であると思います。 &quot; using(MyType myType = new MyType())&quot;ツールチップで。
これにより、視覚的な混乱を継続させることなく、大規模な関数の複雑なネストされたブレースを簡単に理解できるようになります。
これを覚えておくといつも便利だと思う...
明確で適切に記述されたコードは、有能なプログラマーがコードを取得するためにコードが何を行っているかについての十分な説明を提供します。
コードにコメントを残して、なぜコードがそれを行っているのかを説明してください!
つまり、コメントを使用して、コードの読者がアルゴリズムを理解できるように、またはコードが達成するのではなく、どのように達成するのかを理解してください!
やらないでください。あちこちで使用するとノイズが追加され、適切なインデントに加えて読みやすさの問題が解決するはずです。
オフのままにします。同じ場所で終わる複数のブロック(より長いまたはより短いブロック)がある場合にのみ、これを使用する点がわかります。ただし、使用する場合は、自動ツールで追加するよりも、慎重に選択した場所に手動で追加する方が適切です。
特定のタイプのコメントが使用可能かどうかを検討する必要がある場合は、後者の可能性が高いです。
コメントは、理解を容易にするために、特定のコードブロックまたはエンティティ全体を説明するためのものです。書式設定を読みやすくするためではありません。
プラグインを常にこの動作に準拠させることは、肥満でありいです。
コードが何をしているのかを説明するもっと良い方法があることに同意します。
次のような単一の有益なコメントが先行する長いコード本体がある場合 //ワークアイテムを修正します。そのコードを独自のメソッドとしてリファクタリングできます。次に、コメントを新しいメソッドの名前FixWorkItem()として使用します。これを行うと、コードの自己文書化をすばやく行うことができ、以前は気付かなかった設計上の特徴が明らかになることもあります。
IDEによって自動的に処理できる潜在的なリファクタリングとして、そのような1行コメントに注意してください。意図を説明する場合を除き、それ自体を文書化するコードは、最もよく書かれたスタンドアロンのコメントよりも優れています。