C#のコメントってなに？ 動作に影響は？
コメントを入れ方ってどうするの？
ドキュメントコメントって何？
こんにちは、エンジニアでC#ライターの遠藤です。
プログラミング言語を学習していて、早いうちに覚えた方が良いものにコメントがあります。
コメントがないと、プロジェクトの規模が大きくなったときにとても困ります。またプロジェクトの規模に関わらず、デバッグするときに頻繁に使われます。
今回の記事では、そんなC#のコメントについて解説します！
この記事はこんな方に向けて書きました。
- コメントについて知らない方
- コメントについては分かるが、やり方を知らない方
- ドキュメントコメントについて知らない方
この記事を読んでいただければ、コメント・ドキュメントコメントについて理解することができます。
ぜひ最後までお付き合いください。
コメントとは
まずはじめに、ここで言うコメントとは、プログラム中に含まれる処理には含まれないメッセージの事です。
コメントを入れる事によって複雑な処理の概要を説明したり、なぜこの処理が入っているかを書き込んだりすることができます。
なお、コメントは実際の動作に影響を与えないので自由に書き込むことが可能です。
実際の例を見てみましょう。
using System;
class Program
{
static void Main()
{
//メッセージを表示 <-これがコメント
Console.WriteLine("Message");
}
}
このように「//」を使うと、//以降の文字がコメントとして扱われます。
なお、//はその行のみで有効です。複数行コメントをつけたい場合は「/* 複数行コメント */」のように記述する事ができます。
例：
using System;
class Program
{
static void Main()
{
/*
このように
複数行
コメントが
できます。
*/
Console.WriteLine("Message");
}
}
コメントはその処理の概要だったり、どういう意図で実装したかをメモとして残すときに活用します。
コメントアウトとは
コードディングをしていくうえで、コメントアウトは頻繁に使います。
コメントアウトはメッセージをコメントとして残すのではなく、コードをコメントの中に入れる事によってその行の処理を実行させないことを言います。
using System;
class Program
{
static void Main()
{
//以下のコードをコメントアウトして実行させないようにする
//Console.WriteLine("Message1");
Console.WriteLine("Message2");
}
}
実行結果：
Message2
一つ目のWriteLine出力がされませんでした。
コメントアウトの利用目的は、以下のようなケースがあります。
- 実行しなかった場合の処理の差分を確認する場合
- 今は不要な処理だが今後必要になる可能性がある場合、保持のため
ドキュメントコメントとは
C#ではドキュメントコメントと言う、クラスやメソッドの概要、引数の内容などをXML形式で記述するタイプのコメントがあります。
ドキュメントコメントは設計のさいにも便利ですし、クラスやメソッドの概要や目的が一目で分かるのでメンテナンスしやすくなります。また、設定によってXMLファイルに出力することも可能です。
書き方は後にまとめますので、先に実際の例を見てみましょう。
using System;
class Program
{
static void ShowMessage()
{
///
///メッセージを表示するメソッド
///
Console.WriteLine("Message1");
}
static void Main()
{
ShowMessage();
}
}
上記のように、メソッドの上に「///」で書かれているのがドキュメントコメントです。
また、これをXMLファイルに出力すると以下のように表示されます。
myApp メッセージを表示するメソッド
XMLファイルへの出力は、使用するIDE(開発環境)によって変わります。ご自身の環境の手順で試してみてください。
ドキュメントコメントの書きかた
ここでは、ドキュメントコメントの書きかたを簡単にまとめます。
まず、「///」でドキュメントコメントにする事は上述のとおりです。また、複数行をまとめてドキュメントコメントとする場合は「/** 複数行コメント */」で記述することができます。
using System;
class Program
{
/**
<summary>
メッセージを表示するメソッド
</summary>
*/
static void ShowMessage()
{
Console.WriteLine("Message1");
}
static void Main()
{
ShowMessage();
}
}
タグ一覧
ドキュメントコメントはXML形式で記述します。使用するタグ一覧は以下になります。
| タグ名 | 意味 | 備考 |
|---|---|---|
| summary | クラスやメソッドの概要を説明する | |
| remarks | メンバーの説明をする | summaryで指定された情報を補足する |
| returns | 戻り値を説明する | |
| c | テキストをコードとして扱う | summary内などで使う |
| code | 複数行のコードを記述する | |
| example | コード例を記述する(主にcodeを使う) | |
| *exception | 例外について説明する | |
*include | 別のファイル内のコメントを取り込む | |
| para | テキストに構造を追加する(段落) | summary内などで使う |
| *param | そのメソッドのパラメータ(引数)について説明する | |
| paramref | summaryなどの中でパラメータ(引数)を参照するさいに使う | |
| *typeparam | パラメータの型などを説明する | |
| typeparamref | summaryなどの中で型パラメータを参照するさいにつかう | |
| value | プロパティについて説明する | |
| list | リスト・テーブルを説明する | |
| *permission | メンバーへのアクセスのパーミッションを記述する | |
| *see | 他のメンバやフィールドを参照するさいに使う | |
| *seealso | seeの他に参照が必要なものを記述する |
なお、「*」のついているタグはコンパイラのチェックが入ります。
まとめ
今回の記事では、
- コメントについて
- コメントアウトについて
- ドキュメントコメントについて
を解説致しました。
また、ここで紹介したコメント・ドキュメントコメントの主な用途は以下の通りです。
- 複雑な処理の概要を説明
- なぜこの処理が入っているかの説明
- クラスやメソッドの概要を説明
- 引数の内容などを記載
コメントはコードの規模が大きくなるほど重要になってきます。ここで使い方を覚えて、スマートな設計を心掛けてください！
