どう書く。ドキュメントコメント。

オブジェクト倶楽部、コーディング規約の会の「C# コーディング標準」の駄目なところ - 予定は未定Blog版

全く持ってその通りで、このコーディング規約はねえ、害悪を撒き散らしてるだけだよね……。さて、ところでドキュメントコメント。私は、つけます。(プロパティにはつけないかも、メソッドにはつける)。IntelliSense大好きっ子なので。但しほとんどの場合summaryのみを一行。

/// <summary>何たらメソッドです</summary>
public int Method(string input)
{
    // 色々処理ってことで。
    return 0;
}

こんな感じ。何で一行にするかといったら、上にぐちゃぐちゃXMLで書かれてるのって汚いし読みづらいぢゃん、ということもあるんですが主な理由はアウトラインに折りたたんでも解説が見えるから。

ね?///で出てくるものをご丁寧に全部埋めると、アウトラインに畳んだ時に内容が読めなくて困るのです。自分のソースの時は構わないんですが、人のソースを読むときはアウトラインを閉じたり開いたりを多用するので、かなり困ります。というわけで一行summaryお薦め。問題があるとすれば、手書きが面倒(///は一発で出てくるので)ということですが、この程度はキーマクロで記録してショートカットに割り振れば一発なので是非。あと、///で同時に出てくるparamsやreturnsて、大抵は面倒くさいだけであまり必要ないよね。「そういうの、書かなくていいんだよ、summaryだけなら面倒くさくないでしょ?」という心理的な安心感を得られるのも良いです。

ついでに、もう一つ、コメントの飾り枠についても。

// こういうコメントの入れ方は嫌!
class MyClass
{
    // -------------------------
    // Property
    // -------------------------
 
    public int MyProperty { get; set; }
}
 
// これでいいでしょ?
class MyClass
{
    // Property
 
    public int MyProperty { get; set; }
}

領域を目立たせるために囲むんでしょうけど、アウトラインで折りたたむとコメントがばっさり畳まれて見えなくなるんです。無意味な飾りはほんとーに、止めて欲しい。こういうのは一行でいいんです。別に機械に頼ればいいじゃない、機械があるんだから、機械には頼るべき、だからこそソースは機械に優しく書いて欲しいと私は思います。

そういえば#regionの話も出てましたけど、私は#regionはあんまし使いません。かなり好きくない。フィールドとか短いモノを畳まれると、逆にいちいち展開しなきゃならなくて面倒くさいんですよねー。というわけで、よほど長ったらしい状態で任意のグループ分けがしたい時には使いますが、フィールド、プロパティ、メソッド、みたいな分け方のために#regionを使いたくはない。

まあしかし、つまりはアウトラインってあまり使わないのかなあ。「アウトラインの中止」と「定義に折りたたむ」の二つでバサバサと畳んだり開いたりを連発するなんて、しないのかなあ。しないのかも……。周りの人にキモ!このソースキモ!一行summaryキモ!と思われないためにも、むしろ一行summaryをスタンダードにしようの会。コーディング規約ってつまりそういうことでしょうか、なんて独善的な!

勿論、Sandcastleとか絡むんなら別のお話です。

Comment (4)

NyaRuRu : (08/05 05:55)

一行summary自体は嫌いじゃないんですが,
> 主な理由はアウトラインに折りたたんでも解説が見えるから。
に関してはそろそろエディタ側の変更で対処可能なんじゃないですかね.
http://msdn.microsoft.com/ja-jp/magazine/dd722812.aspx#id0400079

>周りの人にキモ!このソースキモ!一行summaryキモ!と思われないためにも、
>むしろ一行summaryをスタンダードにしようの会。
>コーディング規約ってつまりそういうことでしょうか、なんて独善的な!

2002年のコーディング規約(コーディング規約の会のアレ)を2009年に見直すみたいな感じで,今から7年後の2016年にこの辺の事情がどうなっているかは割と楽しみですな.

neuecc : (08/06 08:54)

おお!VBのエディタはデフォルトで複数行でも折りたたみ時にSummaryの中身が表示されてる!
この辺りは共通かと思ってたんですが意外と違うんですね、驚いた……。
そしてVS2010が楽しみです。
このちょっとしたイライラーが解消できるならそれだけで価値が(ぇ

コーディング規約もまたメンテが必要なんですね。
さすがに、他言語に乗り換えるときはスタイルの矯正も出来ますが、
同言語内で変化があった時、体に染みついた習慣を変えられるかというと、うーん。
理想では柔軟に行きたいとは思うのですがすんなりいくかちょびっと不安。

bt : (12/28 15:53)

1ヶ月ぐらい前までVB.NETでコードを書いてたんだけど、C#でコードを書き始めたらアウトラインが折りたたまれる仕様で辟易してたんだ。1行Summaryすげぇ便利だよ。記事を書いてくれてありがとう。

neuecc : (12/30 01:11)

おおー!役に立って嬉しいです。

Name
WebSite(option)
Comment

Trackback(0) | http://neue.cc/2009/08/05_183.html/trackback

Search/Archive

Category

Profile


Yoshifumi Kawai
Microsoft MVP for Developer Technologies(C#)

April 2011
|
July 2021

Twitter:@neuecc
GitHub:neuecc
ils@neue.cc