///コメントブロックが重要な理由

誰かがすべてのメソッドの前に/// <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、ライブラリなどのパブリッククラス、メソッド、およびプロパティで使用することをお勧めします。少なくとも、彼らはそれを使用する開発者を支援するドキュメントを生成し、それらを書くために。

しかし、とにかくそれをスライスしたり、メンテナンスしたり、削除したりします。

戻って新しいコードに対応するためにコメントを編集し続ける必要があることがわかった場合、そもそも間違ったコメントをしている可能性があります。要約要素には、要約-要約するものの内容と理由を正確に含める必要があります。

コメントで何かがどのように機能するかを説明すると、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)。

ライブラリを除いてそれらを使用する

それは彼らが役に立つ時間です。XMLドキュメントの生成を有効にすると、プロジェクトなしでアセンブリへの参照がインテリセンスでより詳細に表示されます。

しかし、現在のプロジェクトの内部については、彼らは邪魔をします。

私はそれらを使用しますが、他の人が普遍的に言っていないように。小さなメソッドの場合は、説明しているコードよりも簡単に大きくなります。これらは、システムを初めて使用する人に提供できるドキュメントを生成するのに最も役立ち、学習中に参照することができます。とはいえ、プログラマーとしては、通常、いくつかのコードが何であるかを突き止めることができます。それは場合は持っているコードで、その後どこかに書き留めなければ、それが最も可能性が高い（可能性が高い漂っいくつかのWord文書より）更新滞在することです場所です。

私はVBで同等のものを使用します（C＃を使用させないため-明らかに難しすぎます...コメントはありません）。ほとんどの場合、コメントを変更する必要がないようにするため、または「非同期」にするためだけに、プロシージャまたは関数が完了する前にそれらを挿入するまで待機します。

私は必ずしも小説を書いているわけではありません-基本、パラメータの説明、いくつかの発言（通常はそこに「普通ではない」ことが起こっているとき） 「今のところ」選択はありません。）（ええ、私は、「今のところ」は何年も続くことを知っています。）

コメントなしのコードにひどくイライラしています。コンサルタントが私たちのコンポーネントの1つの初期バージョンを作成し、何もコメントせず、彼の名前の選択はあちこちで望まれています。彼は1年以上経ちましたが、私たちは彼自身のものを整理しています（私たち自身のものに取り組むことに加えて）。