誰かがすべてのメソッドの前に/// <summary>
コメントブロック(C#)を付ける必要があると言っていましたが、その理由は説明されませんでした。
私はそれらを使い始めて、彼らが私をかなりいらいらさせているのを見つけたので、ライブラリと静的メソッドを除いてそれらを使うのをやめました。それらはかさばり、私はいつもそれらを更新するのを忘れています。
コードで/// <summary>
コメントブロックを使用する十分な理由はありますか?
私はいつも//
コメントをいつも使用しています。それは私が気になっていた/// <summary>
ブロックだけです。
可能な限りそれらを使用してください。
はい、それらはメソッドのドキュメントになる特別なコメントです。生成された<summary>
の内容、パラメータータグなどは、あなたまたは他の誰かがメソッドを呼び出す準備ができているときに、インテリセンスで表示されます。彼らは基本的に、ファイル自体に行って何をしているのかを理解しなくても(またはメソッドのシグネチャを読んで最善を期待して)、メソッドやクラスのすべてのドキュメントを見ることができます。
はい、保持したいもの、または共有する可能性があるものには絶対に使用してください。
また、それらを Sandcastle および Sandcastle Help File Builder と組み合わせて使用すると、XML出力を取得して、MSDNスタイルの美しいドキュメントに変換できます。
最後に作業した場所で、毎晩ドキュメントを再構築し、内部のホームページとしてホストしました。会社のイニシャルはMFだったので、MFDNでした;)
通常は、簡単に共有できる.chmファイルを生成するだけです。
あなたがそれをMSDN形式で見始めると、あなたがすべてを文書化することに中毒になるということに驚くでしょう!
コーディング標準がそのようなコメントの使用を要求する場合(そしてAPIまたはフレームワークのコーディング標準がそれを要求する場合があります)、選択の余地はなく、そのようなコメントを使用する必要があります。
それ以外の場合は、そのようなコメントを真剣に使用しないことを検討してください。ほとんどの場合、次のようにコードを変更することで回避できます。
/// <summary>
/// Checks if a user is authorized to access the resource
/// </summary>
public bool SecurityCheck( User user ) {
}
に
/// <summary>
/// Checks if a user is authorized to access the resource
/// </summary>
public bool IsAuthorizedToAccessResource( User user ) {
}
に
public bool IsAuthorizedToAccessResource( User user ) {
}
クラス、メソッド、およびプロパティの名前は自明である必要があるため、これらが必要な場合は、おそらくにおいです。
ただし、API、ライブラリなどのパブリッククラス、メソッド、およびプロパティでそれらを使用することをお勧めします。少なくとも、それらは、それを使用する開発者を助けるためのドキュメントを生成し、それらを書く。
しかし、とにかくそれをスライスするか、維持するか、削除します。
新しいコードに対応するために戻ってコメントを編集し続ける必要があるとわかった場合、そもそもコメントを間違っている可能性があります。要約要素には、正確に、要約-whatおよびwhyが含まれている必要があります。
説明howコメントで機能するものはDRYに違反しています。コードが十分に自己記述的でない場合は、戻ってリファクタリングする必要があります。
はい、作成しました。 [新しいシステムをゼロから構築する場合]
いいえ、私はそれらの恩恵を受けたことはありません。 【メンテナンスが必要な既存システムで作業する場合】
「要約」コメントは最終的にコードと同期しなくなる傾向があることがわかりました。そして、ひどい振る舞いのコメントに気づいたら、そのプロジェクトに関するすべてのコメントへの信頼を失う傾向があります。どのコメントを信頼すべきか、あなたには決してわかりません。
何かをすることを忘れても、それは悪い考えにはなりません。ドキュメントの更新を忘れている。これらは私のプログラミングで非常に有用であることがわかりました。私のコードを継承する人々は、それらを持っていることに感謝しています。
これは、コードを文書化する最も目立つ方法の1つです。
インラインドキュメンテーションを読むためにソースコードを見つける必要があるか、コードが何をするかを説明するドキュメントを掘り下げるのは苦痛です。インテリジェンスを通じて何か便利なポップアップを表示できる場合、人々はあなたを愛するでしょう。
"それは私のようにとても使われなければなりません;)"
以前はコメント(///)で遊んでいました。クラスの場合は、このようなコメントを簡単に行うことができます
namespace test
{
/// <summary>
/// Summary description for Calendar.
/// </summary>
public partial class DatePicker : System.Web.UI.Page
{
ただし、メソッドの場合は、パラメータと戻り値の型の説明を追加することで、さらにアドオンできます。
/// <summary>
/// Assign selected cases to the participating users based on the filters and configurations
/// </summary>
/// <param name="noOfParticipants">No. of participants to the Table</param>
/// <param name="value">Value of the participant</param>
/// <returns>No Of Cases Assigned on successfull completion</returns>
public long AssignCasesToParticipatingUsers(int noOfParticipants,string value)
{
このコメントの作成にショートカットを使用できます(///+Tab)
。
VBで同等のものを使用します(C#を使用できないため-どうも難しいです...コメントはありません)。非常に便利です。ほとんどの場合、プロシージャまたは関数は、コメントを変更する必要がないようにするため、またはコメントを「非同期」にするために、それらを配置する前にほぼ完了します。
私は必ずしも小説を書くわけではありません-基本、パラメーターの説明、およびいくつかのコメント(通常、そこで「異常な」ことが起こっている場合)-回避策または他のがらくたがありませんが、そこにはありません「今のところ」は選択の余地がありません。
コメントされていないコードに私はひどくイライラしています。コンサルタントは、コンポーネントの1つの初期バージョンを作成し、何もコメントしませんでした。彼の名前の選択は、あちこちで望まれています。彼は1年以上経ちますが、私たちは彼のもの(私たちのものに取り組んでいることに加えて)をまだ整理しています。
ライブラリ以外で使用する
それは彼らが役に立つ時です。 XMLドキュメントの生成がオンになっていると、プロジェクトなしでアセンブリを参照すると、インテリセンスでより詳細に表示されます。
しかし、現在のプロジェクトの内部については、彼らは邪魔になります。
私はそれらを使用しますが、他の人が普遍的に言っていないように。小さなメソッドの場合、それらは説明しているコードよりも簡単に大きくなる可能性があります。これらは、システムを初めて使用する人に与えることができるドキュメントを生成して、学習中に参照できるようにするために最も役立ちます。とはいえ、プログラマーとしては、通常、一部のコードの意味を理解することができます。コメントを添えて私たちを導き、松葉杖として振る舞うのはいいことです。 hasと書き留めると、コード内で更新されたままになる可能性が最も高くなります(Word文書が浮かんでいるよりも可能性が高くなります)。