初心者必見!C#のコメント・ドキュメントコメントまとめ

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そのメソッドのパラメータ(引数)について説明する
paramrefsummaryなどの中でパラメータ(引数)を参照するさいに使う
*typeparamパラメータの型などを説明する
typeparamrefsummaryなどの中で型パラメータを参照するさいにつかう
valueプロパティについて説明する
listリスト・テーブルを説明する
*permissionメンバーへのアクセスのパーミッションを記述する
*see他のメンバやフィールドを参照するさいに使う
*seealsoseeの他に参照が必要なものを記述する

なお、「*」のついているタグはコンパイラのチェックが入ります。

まとめ

今回の記事では、

  • コメントについて
  • コメントアウトについて
  • ドキュメントコメントについて

を解説致しました。

また、ここで紹介したコメント・ドキュメントコメントの主な用途は以下の通りです。

  • 複雑な処理の概要を説明
  • なぜこの処理が入っているかの説明
  • クラスやメソッドの概要を説明
  • 引数の内容などを記載

コメントはコードの規模が大きくなるほど重要になってきます。ここで使い方を覚えて、スマートな設計を心掛けてください!

この記事を書いた人

【プロフィール】
DX認定取得事業者に選定されている株式会社SAMURAIのマーケティング・コミュニケーション部が運営。「質の高いIT教育を、すべての人に」をミッションに、IT・プログラミングを学び始めた初学者の方に向け記事を執筆。
累計指導者数4万5,000名以上のプログラミングスクール「侍エンジニア」、累計登録者数1万8,000人以上のオンライン学習サービス「侍テラコヤ」で扱う教材開発のノウハウ、2013年の創業から運営で得た知見に基づき、記事の執筆だけでなく編集・監修も担当しています。
【専門分野】
IT/Web開発/AI・ロボット開発/インフラ開発/ゲーム開発/AI/Webデザイン

目次