C#コーディングルール_#26_コメントはスラッシュ４つ

今回はコメントに関するルールを解説していきます。

スラッシュ２つでコメントを書く

C#ではスラッシュ２つでコメントが記述できますが，そのまま書くと警告が出ます。

SA1005

スラッシュ２つに続けてコメントを記載するとSA1005の警告が出ます。

WEBサイトで原因を確認すると，単一のスペースで始まっていないといっています。要するに，スラッシュ２つの後に半角のスペースを１つ入れてからコメントを書くようにとなっています。またはスラッシュを４つ書いてからコメントを書いてもOKです。

なぜこのルール

このルールを作った意図は分かりませんが，私は，できるだけコメントをメソッド内に書かないようにするためのルールと思っています。

メソッドの解説はXMLコメントに込める

メソッド内にコメントを入れる必要があるという事は，そのメソッドが複雑か，長い，要するに，コードを読んだだけでは意味が分かりにくい場合です。という事は，その複雑なコード自体が問題で，安易にコメントを入れることで解決しないように努めてほしいのです。

メソッドにはXMLコメントを書きます。このメソッドで何をしているかを書いています。なのでメソッド内にコメントを書かなくても，コードを読めば意味が解るはずです。それでもあえてコメントがいるという事は，コードが複雑すぎないか？，メソッドを分割できない？というように，もう一度コードを確認してほしいのです。

それでもコメントを書きたいとき

それでもコメントを書きたいときがあります。時々どうしても特殊な処理が必要になり，コメントを書きたい場合があります。その場合はスラッシュ４つで書いてください。

こんな感じで，スラッシュ４つで書けば，警告は消えます。よくコメントとコードがあってない場合があります。コードを修正してコメントはそのままという事があり，メソッド内のコメントは時にプログラマーを惑わせます。できるだけ書かないようにします。

メンバーへの教育

開発メンバーには，このような理由を説明し，できるだけメソッド内にコメントは書かずに，XMLコメントで表現するように説明しましょう。処理が複雑になる場合や，長くなる場合は，メソッドを分割するなどして，それぞれにXMLコメントを付けることで対応することを検討しましょう。それでも仕方がない場合はスラッシュ４つでコメントを書きましょう。