演習 - 効果的なコードコメントを作成する

13 分

この演習では、コードにメモを追加し、特定のコード行のコンパイルを一時的に無効にします。次に、C# コンパイラによって空白文字が認識されるしくみと、空白文字を使用してコードを読みやすくする方法について説明します。

コードコメントとは

コードコメントとは、現在の行でコードコメント記号の後にあるすべてをコンパイラに無視させるための命令です。

// This is a code comment!

最初は役に立つように見えないかもしれませんが、次の 3 つの状況で役に立ちます。

コードの記述の意図についてのメモを残したいとき。特に困難なコーディング命令のセットを記述するときに、目的または思考プロセスを説明するコードコメントを含めると便利です。将来のあなたが自分に感謝することになるでしょう。
アプリケーションからコードを一時的に削除して別のアプローチを試したいが、新しいアイデアが機能することにまだ自信が持てないとき。コードをコメントアウトし、新しいコードを記述して、新しいコードが希望どおりに動作することを確信できたら、古い (コメント化した) コードを安全に削除することができます。
後で特定のコードを確認することを忘れないよう、TODO のようなメッセージを追加するとき。慎重に使用する必要はありますが、これは有効なアプローチです。気になるコード行を目にしたときに、別の機能の作業を行っていることがあります。そのようなときは、新しい心配事を無視するのではなく、後で調査するためにマークしておくことができます。

注

コードコメントは、コードではできないことを言うために使用する必要があります。開発者はコードを更新しても、コードのコメントを更新するのを忘れることがよくあります。個々のコード行の動作方法に関するコメントを追加するのではなく、より高度なアイデアにコメントを使用することをお勧めします。

コーディング環境を準備する

このモジュールには、サンプルコードをビルドして実行するプロセスをガイドする演習が含まれています。これらのアクティビティを完了するために、開発環境として Visual Studio Code を使用することをお勧めします。これらのアクティビティに Visual Studio Code を使用すると、世界中のプロフェッショナルが使用する開発環境でコードの記述と実行をより快適に行うことができます。

Visual Studio Code を開きます。

Visual Studio Code は、Windows の [スタート] メニュー (別の OS の場合は同等のリソース) を使用して開くことができます。
Visual Studio Code の [ファイル] メニューで、[ フォルダーを開く] を選択します。
[ フォルダーを開く] ダイアログで、Windows デスクトップフォルダーに移動します。

コードプロジェクトを保持するフォルダーの場所が別にある場合は、代わりにそのフォルダーの場所を使用できます。このトレーニングでは、見つけやすく覚えやすい場所を用意することが重要です。
[ フォルダーを開く ] ダイアログで、[フォルダーの選択] を 選択します。

作成者を信頼するかどうかを確認するセキュリティダイアログが表示された場合は、[ はい] を選択します。
Visual Studio Code ターミナル メニューで、[ 新しいターミナル] を選択します。

[ターミナル] パネルのコマンドプロンプトに、現在のフォルダーのフォルダーパスが表示されることを確認します。次に例を示します。
```
C:\Users\someuser\Desktop>
```
注

サンドボックスやホスト環境ではなく、自分の PC で作業しており、この C# シリーズの他の Microsoft Learn モジュールを完了している場合は、コードサンプル用のプロジェクトフォルダーが既に作成されている可能性があります。その場合は、次の手順 (TestProject フォルダーにコンソールアプリを作成するために使用される) をスキップできます。
ターミナルコマンドプロンプトで、指定したフォルダーに新しいコンソールアプリケーションを作成するには、次のプロンプトを入力します。
```
dotnet new console -o ./CsharpProjects/TestProject
```
この .NET CLI コマンドでは、.NET プログラムテンプレートを使用して、指定したフォルダーの場所に新しい C# コンソールアプリケーションプロジェクトを作成します。このコマンドでは、CsharpProjects および TestProject フォルダーが自動的に作成され、.csproj ファイルの名前として TestProject が使用されます。

ファイルが既に存在することを示すメッセージが表示される場合は、次の手順に進みます。既存のプロジェクトファイルを再利用します。
エクスプローラービューで、 CsharpProjects フォルダーを 展開します。

TestProject フォルダーと、Program.cs という名前の C# プログラムファイルと TestProject.csproj という名前の C# プロジェクトファイルの 2 つのファイルが表示されます。
Visual Studio Code の [ファイル] メニューで、[ フォルダーを開く] を選択します。
[ フォルダーを開く ] ダイアログで、 CsharpProjects フォルダーを選択し、[フォルダーの選択] を 選択します。
エクスプローラービューで、TestProject フォルダーを展開し、 Program.csを選択します。
既存のコード行を削除します。

この C# コンソールプロジェクトを使用して、このモジュール中のコードサンプルを作成、ビルド、および実行します。
[ターミナル] パネルを閉じます。

コードコメントを作成して使用する

このタスクでは、さまざまな種類のコードコメントを作成および削除します。

[Visual Studio Code エディター] パネルに次のコードを入力します。

string firstName = "Bob";
int widgetsSold = 7;
Console.WriteLine($"{firstName} sold {widgetsSold} widgets.");

コードコメントとリビジョンを使用してコードを変更するには、次のようにコードを更新します。

string firstName = "Bob";
int widgetsPurchased = 7;
// Testing a change to the message.
// int widgetsSold = 7;
// Console.WriteLine($"{firstName} sold {widgetsSold} widgets.");
Console.WriteLine($"{firstName} purchased {widgetsPurchased} widgets.");

少し時間をかけて、ご自分のコメントとコードの更新を確認してください。

変更される可能性のあるものを文書化したり、新しいメッセージをテストするときに、古いメッセージを一時的に無効にしたりするためにコードコメントが使用されていることに注目してください。次の手順では、更新プログラムをテストします。新しいコードに問題がなければ、コメントアウトされた古いコードを安全に削除することができます。これは、作業中のコードを完全に削除する準備ができたことが確信できるまで、より安全で体系的なアプローチで修正する方法です。
[Visual Studio Code ファイル] メニューの [ 保存] をクリックします。
エクスプローラービューで、TestProject フォルダーの場所でターミナルを開くには、[ TestProject] を右クリックし、[ 統合ターミナルで開く] を選択します。
ターミナルのコマンドプロンプトで、「 dotnet run 」と入力し、Enter キーを押します。

次の出力が表示されます。
```
Bob purchased 7 widgets.
```
ここでも、更新に問題がなければ、コメントアウトされた古いコードを削除してください。

コードコメントを削除してください。

コードは以下と一致するようになります。

string firstName = "Bob";
int widgetsPurchased = 7;
Console.WriteLine($"{firstName} purchased {widgetsPurchased} widgets.");

複数の行をコメントアウトするブロックコメントを適用するには、次のようにコードを更新してください。
```
/*
string firstName = "Bob";
int widgetsPurchased = 7;
Console.WriteLine($"{firstName} purchased {widgetsPurchased} widgets.");
*/
```
ブロックコメントは、長いコメントを記述する必要がある場合や、多くのコード行を削除する必要がある場合に最適です。ブロックコメントでは、コードの先頭に /* を使用し、末尾に */ を使用します。ブロックコメントの使用は、3 行以上のコードを無効にするための最も迅速で簡単な方法です。

既存のコードを次の内容と置き換えてください。

Random random = new Random();
string[] orderIDs = new string[5];
// Loop through each blank orderID
for (int i = 0; i < orderIDs.Length; i++)
{
    // Get a random value that equates to ASCII letters A through E
    int prefixValue = random.Next(65, 70);
    // Convert the random value into a char, then a string
    string prefix = Convert.ToChar(prefixValue).ToString();
    // Create a random number, pad with zeroes
    string suffix = random.Next(1, 1000).ToString("000");
    // Combine the prefix and suffix together, then assign to current OrderID
    orderIDs[i] = prefix + suffix;
}
// Print out each orderID
foreach (var orderID in orderIDs)
{
    Console.WriteLine(orderID);
}

注

このコードリストには、初めて目にする C# の概念が多く含まれるかもしれません。読む人がコードの目的を理解するためにコメントがどれほど役に立つかを確認するのに、コードで行われていることを理解する必要はありません。

少し時間をかけて、コードの目的を理解できるかどうかを確認してください。

コメントがあると、コードで行われていることを解明できる場合があります (コメントで現在の状態が正確に記述されていて、コードの更新に合わせてコメントが更新されていることが前提です)。ところで、このコードが存在する理由を推測できますか。何らかのコンテキストを提供し、その目的が記述されている説明がコードファイルの上部にあれば、便利ではないでしょうか?
コメントを改善する方法を検討してください。

これらのコメントには、次の 2 つのメインの問題があることに注目してください。
- コードのコメントで、個々のコード行の明らかな機能について必要のないことが説明されています。このようなコメントは、C# または .NET クラスライブラリのメソッドの動作を説明するだけなので、低品質のコメントと見なされます。読む人がこれらのアイデアをよく知らない場合は、learn.microsoft.com や IntelliSense を使用して検索できます。
- コードのコメントで、コードによって解決されている問題のコンテキストが提供されていません。このようなコメントは、読む人がこのコードの目的についての分析情報を得られないため (特に大規模なシステムに関連している場合)、低品質のコメントと見なされます。

既存のコメントを削除してください。

コードは以下と一致するようになります。

Random random = new Random();
string[] orderIDs = new string[5];

for (int i = 0; i < orderIDs.Length; i++)
{
    int prefixValue = random.Next(65, 70);
    string prefix = Convert.ToChar(prefixValue).ToString();
    string suffix = random.Next(1, 1000).ToString("000");

    orderIDs[i] = prefix + suffix;
}

foreach (var orderID in orderIDs)
{
    Console.WriteLine(orderID);
}

コードが、既に雑然とはしていないことに注目してください。

コードの概要的な目的を説明するコメントを追加するには、次のようにコードを更新します。

/*
  The following code creates five random OrderIDs
  to test the fraud detection process.  OrderIDs 
  consist of a letter from A to E, and a three
  digit number. Ex. A123.
*/
Random random = new Random();
string[] orderIDs = new string[5];

for (int i = 0; i < orderIDs.Length; i++)
{
    int prefixValue = random.Next(65, 70);
    string prefix = Convert.ToChar(prefixValue).ToString();
    string suffix = random.Next(1, 1000).ToString("000");

    orderIDs[i] = prefix + suffix;
}

foreach (var orderID in orderIDs)
{
    Console.WriteLine(orderID);
}

コメントの有用性は主観的です。コードの読みやすさに関連するすべての事柄において、自分が最適と判断するように使用する必要があります。コードをわかりやすくするために最善と思われることを行ってください。

要点

この演習では主に次のことを学習しました。

コードによって解決される問題について、自分のためにわかりやすいメモを残すには、コードコメントを使用します。
C# または .NET クラスライブラリの動作について説明するコードコメントは使用しないでください。
別のソリューションを一時的に試してみるときは、新しいコードソリューションを使用する準備ができるまでは、コードのコメントを使用し、準備ができたら古いコードを削除できます。
コメントを信頼してはいけません。多くの変更や更新が行われた後では、コードの現在の状態が反映されていない可能性があります。

演習 - 効果的なコード コメントを作成する

コード コメントとは

コーディング環境を準備する

コード コメントを作成して使用する

要点

フィードバック

演習 - 効果的なコードコメントを作成する

コードコメントとは

コードコメントを作成して使用する