C#コーディングルール

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

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

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

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

SA1005

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

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

なぜこのルール

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

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

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

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

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

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

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

メンバーへの教育

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

C#コーディングルール

■4700人以上が受講している動画コースはこちらからご確認ください

#01_はじめに
#02_名前の付け方
#03_名前付けのガイドライン
#04_パスカルケースとキャメルケース
#05_パスカルとキャメルの内訳
#06_パスカルとキャメルの実演
#07_2文字の略語は大文字にする
#08_名前空間のガイドライン
#09_ローカルルールについて
#10_private変数にアンダーバーを付ける
#11_コントロールの名付け
#12_クラス名とファイル名の名づけ
#13_StyleCopAnalyzersについて
#14_StyleCopAnalyzersのインストール
#15_ネームスペースの調整
#16_SA0001_プロパティのビルドのXMLでファイルを指定しておくと消える
#17_CS1591_XMLコメントなし
#18_SA1101_thisが付いていない
#19_不要なルールを非表示にする方法
#20_SA1200_usingの場所
#21_SA1400_アクセス修飾子が明示的に定義されていない
#22_その他不要なルールを非表示
#23_コンストラクタとデストラクタを作成
#24_Private変数とパラメータ変数の命名
#25_中括弧の省略禁止と改行
#26_コメントはスラッシュ4つ
#27_プロパティのXMLコメント
#28_コンストラクタやプロパティの書く順番
#29_アクセスレベルを加味した書く順番
#30_インタフェースのIとファイル名の不一致
#31_最後に

■4700人以上が受講している動画コースはこちらからご確認ください