TimeSpan.Add メソッドで加算されないと思ったら

C#（というか.NET Framework）で、TimeSpan.Addを使うと、自分自身に加算ではなく、加算した結果を別のオブジェクトで返してくる。

たぶんTimeSpanが構造体であることが理由なのかもしれないけど、そこらへんは詳しく調べていない。

いつもListクラスの類でAddメソッドをよく使っているので、Addメソッドというのは自分自身に加算されるものだと思い込んでいた。

この思い込みにさらに拍車をかけたのが、MSDNのクラス ライブラリ リファレンスで、.NET Framework2のTimeSpan.Addメソッドのページ冒頭には「指定した TimeSpan と、このインスタンスを加算します。 」とだけ書かれていた。

この文だけでは加算した結果がどうなるかがわからないが、最初にこれを読んだため、さらにAddメソッドは自分自身に加算されるものだと勝手に思ってしまった。（後でよく見てみると下の解説に「戻り値は新しい TimeSpan です。元の TimeSpan は変更しません。」と書かれているので、よく読めばわかるといわれればそれまでですが）

それで自分自身に加算されることを前提にしてプログラムを組んでうまく動作せずに、加算されるものと思い込んでいたのでしばらく原因がわからず悩んでしまった。

最終的には、「TimeSpan.Add」で検索して思い込みに気づいた。

あとで再びMSDNのクラス ライブラリ リファレンスで調べてみると、.NET Framework4のTimeSpan.Addメソッドのページだけが冒頭に「指定された TimeSpan オブジェクトとこのインスタンスの合計を値に持つ、新しい TimeSpan オブジェクトを返します。」と結果がどうなるかわかる説明になっている。

こうした仕様は少し紛らわしいと思うけど、変更できないだろうし、変更しても混乱するだけなのだろう。せめて.NET Framework2から3.5のライブラリリファレンスの文を4の文にしてほしいと思った。