none
イベントやイベントハンドラーのコメントの書き方について RRS feed

  • 質問


  • こんにちは。
    いろいろなイベントのコメント文について質問です。
    おそらく、これはいくらかプログラマーごとの生理の問題であるように思うのですが、質問できるプログラマーがいないのでお聞きしたいです。

    メソッドのコメントは、そのメソッドが実行する内容を概要、注釈にして表すものだと考えています。
    これは、interface 関係にあるプロパティのコメントにちょっとだけ不思議な思いと面倒な思いをしていますが、違和感は少ないです。


    気になっているのが、イベントやデリゲートのコメントです。
    例えば、依存関係プロパティのプロパティ値が変更されたときに呼び出されるCallbackEventのときは、呼び出されるタイミングについて注釈しておいてもよいような気がしますし、メソッドと同じで中でやっていることを書いてもよい気もします。

    C#のイベント命名規則ガイドラインは、こんな感じです。
    https://msdn.microsoft.com/ja-jp/library/cc433259(v=vs.71).aspx

    私も、イベントは On + **** + (ed or ing) のような慣用的な命名規則をしていることが多いのですが、下記のような感じになるとメソッドと比べると、少しもやっとした気持ちになります。
    もやっと感じるのは、イベントを表すメソッド名と、コメントで書かれている内容が少し異なるような気持ちになるからだと思います。
    ChangeToolTipColor(Brushes.Black); みたいなメソッドを呼び出していても、同じような感じがしています。そうでもないのでしょうか?

    /// <summary>
    /// <see cref="Ball"/> プロパティの値が変更されたとき、 ToolTips のカラーを変更します。
    /// </summary>
    /// <param name="obj">プロパティ値が変更された <see cref="*****"/> オブジェクト(未使用)。</param>
    /// <param name="e">プロパティ値が変更された内容を表すイベント情報引数。</param>
    private static void OnBallChanged(DependencyObject obj, DependencyPropertyChangedEventArgs e)
    {
    ...
    }

    もうひとつは、普通のEventHandlerのコメントと、ハンドラーに紐付けたイベントメソッドのコメントです。

    例えばButtonにある OnClick イベントハンドラーのコメントは、どういうときに呼ばれるのかをコメントする感じでしょうか。
    ハンドラーに紐付けたイベントは、何をしているのかと、具体的なボタンがどれかを書いたりするのでしょうか。
    ただ、後者の紐付けたイベントメソッドは、イベントと表すメソッド名と、中でしていることの内容について先述したことと同じもやもやを覚えます。

    特にイベントのコメントについて、単純にどのように考えているのか気になっています。
    また、単純なイベントは、コメントが省略されていることも少なくないと思います。
    EventHandler のコメントを除けば、コントロール内イベントはPrivateな状態であんまり製作者以外は大体見なくてもよい状態です。

    /// <summary>
    /// <see cref="Button" /> コントロールをマウスで押下したときに発生するイベント。
    /// </summary>
    public event EventHandler OnClicked;
    
    /// <summary>
    /// 危険を示すメッセージのポップアップウィンドウを表示します。
    /// <para>
    /// 危険ボタンを押下したときに、ポップアップ表示されます。
    /// </para>
    /// </summary>
    /// <param name="obj">Clickイベントが実行された <see cref="*****"/> オブジェクト(未使用)。</param>
    /// <param name="e">イベント情報のない引数(未使用)。</param>
    public void OnClicked(object sender, EventArgs e)
    {
    ....
    }


    カプセル化されていてあんまりレビューしない(例えば、独自カスタムコントロールのLoadedイベントのコメントとか)ものは、省略することも多いのでしょうか?
    もちろん、publicのプロパティやメソッドよりも、privateのプロパティやメソッドにコメントが書かれていても変な話だと思いますが。


    これらについて、よいアイデアや指針があれば教えて欲しいです。
    よろしくお願いします。

    • 編集済み ichiethel 2017年2月7日 6:35
    2017年2月7日 6:34

すべての返信


  • C#のイベント命名規則ガイドラインは、こんな感じです。
    https://msdn.microsoft.com/ja-jp/library/cc433259(v=vs.71).aspx

    引用されているのはかなり古いですね。

    https://msdn.microsoft.com/ja-jp/library/ms229042(v=vs.110).aspx

        * https://msdn.microsoft.com/ja-jp/library/ms229002(v=vs.110).aspx

        * https://msdn.microsoft.com/ja-jp/library/ms229011(v=vs.110).aspx

    自動翻訳で見にくい場合は、原文でGoogle翻訳をかけてみてください

    2017年2月9日 13:14
  • 名前の使い方ですが、先ずOnの使い方がおかしいです。

    有名なINotifyPropertyChangedを見てみましょう。

    https://msdn.microsoft.com/ja-jp/library/system.componentmodel.inotifypropertychanged(v=vs.110).aspx

    *  イベント名: PropertyChanged

    名詞+過去形ですね。この場合はプロパティの値が変わった後のタイミングで呼び出されることも名前で示しています。

    * イベントハンドラの引数: PropertyChangedEventArgs

    https://msdn.microsoft.com/ja-jp/library/system.componentmodel.propertychangedeventargs(v=vs.110).aspx

    イベント名+EventArgsです

    * イベントハンドラの型名(デリゲート): PropertyChangedHandler

    https://msdn.microsoft.com/ja-jp/library/system.componentmodel.propertychangedeventhandler(v=vs.110).aspx

    イベント名+EventHandlerです

    次はインターフェースを実装したクラスの例です。やっとOnが出てきます。

    https://github.com/PrismLibrary/Prism/blob/master/Source/Prism/Mvvm/BindableBase.cs

    インターフェースを実装したクラスでイベントを呼び出すメソッドにOnを付けていますよね?

    Onの他にもRaiseやNotifyを付ける場合があります。RaisePropertyChangedとかNotifyPropertyChangedとかですね。

    通知を行うOnPropertyChangedを呼んでいるSetPropertyはプロパティのSetterから呼びます。

    https://github.com/PrismLibrary/Prism/blob/master/Source/Prism.Tests/Mocks/ViewModels/MockViewModel.cs

    値を変更したらイベント変数にイベントハンドラを登録したオブジェクトに通知が飛ぶわけですよね?

    では、イベントの通知を受けるイベントハンドラはどうやって命名するか?

    MockViewModelなら、親に一つしかないならMockViewModel_ProperyChangedとか、

    MockViewModel mockViewModel;

    とか宣言されていたら、

    mockViewModel_ProperyChangedとか名前を付けるのが一般的ではないですかね。

    例えばWindowFormsにあるようなハンドラの命名の仕方です。

    * Form1クラスのLoadedのハンドラならForm1_Loaded

    * textBox1のClickedのハンドラならtextBox1_Clicked

    さて、PropertyChangedのイベントハンドラの実装はどうなるかというと、MockViewModelにプロパティが複数あるなら引数の名前をチェックして、プロパティ名に応じた処理を行うと思います。

    > 危険ボタンを押下したときに、ポップアップ表示されます

    showDangerousMessageButton_Clicked

    とかですかね? (文法苦手なのですみません・・・間違ってるかも)

    つまり、コメントに詳しく書くのではなく、コメントと一致するような名前を付けるわけです。
    • 編集済み tmori3y2 2017年2月9日 15:15
    2017年2月9日 13:43
  • さて、本題のコメントの話ですが、DoxygenやDocFxなどでAPIのドキュメントを作る場合もありますが、コメントを付ける一番の動機はインテリセンスです。

    そうすると、表示されるのはsummaryとparam/typeparam、それとexceptionだけです。

    (returnは表示されないから、GetPropertyとかでProperty値ではなく、取得成功のboolとか返すメソッドはシグネーチャがおかしいって話になります)

    更に、インテリセンスだとすると一行コメントが望まれます。

    となると、詳しい説明はNGです。

    極端な話、GhostDocやAtomineer Pro Documentationのようなツールで命名規則に従った名前から自動で英文コメントを吐くぐらいがちょうどよいわけです。(日本語は自動翻訳で・・・)

    「でも、それだとわからないよ・・・」

    という場合は設計が複雑か名前の付け方がおかしいとか、そういうことなんでしょう・・・

    実際には、そう上手くはいかないので、wikiとかmdファイルとか、plantumlとかで追加のドキュメントを書いて、「あとはそっち見てね」というのが、これから主流になっていくんじゃないかと思ってます。

    ちなみに、privateの話ですが、インテリセンスで使うことを考えると、別にコメントを付けても良いですよね?


    • 編集済み tmori3y2 2017年2月9日 15:16
    2017年2月9日 14:08
  • 英語でコメントを付けるメリットは他にもあります。

    VS2015でStyleCop.Analyzersを使うと何が起こるか?

    https://github.com/DotNetAnalyzers/StyleCopAnalyzers

    「コンストラクタには標準のコメントがあるよ」と英語の標準コメントを付け直すように勧められます。

    setterなし、private setterのコメントを「Get or set ・・・」なんて書いてると、「or set」は削除しなさいと言われます。

    2017年2月9日 15:20