練習 - 建立有效的程式碼註解

13 分鐘

在此練習中，您將在程式碼中加入備註，並在編譯期間暫時停用某些程式碼行。接著，您將探討 C# 編譯器如何了解空白字元，以及如何使用空白字元來提高程式碼的可讀性。

什麼是程式碼註解？

程式碼註解是編譯器的一種指令，可忽略目前行中程式碼註解符號之後的所有內容。

// This is a code comment!

這乍看之下似乎沒有用，不過這在三種情況下很有用：

當您想要為程式碼片段的意圖留下一個備註時。當您撰寫一組特別具挑戰性的程式碼撰寫指令時，包含描述用途或思考過程的程式碼註解會很有幫助。您的未來將會感謝您。
當您想要暫時移除應用程式中的程式碼以嘗試不同的方法，但您還不確信新的構想是否有效時。您可以將程式碼註解化、撰寫新的程式碼，然後在您確信新程式碼以您想要的方式運作之後，就可以安全地刪除舊的程式碼 (已加上註解的程式碼)。
加入如 TODO 的訊息，以提醒您之後查看特定的程式碼片段。儘管您應該謹慎使用此方法，但它是個很實用的方法。當您讀取一行可能會有顧慮的程式碼時，您可能正在使用另一個功能。您可以將其標示為稍後進行調查，而不是忽略新的顧慮。

注意

程式碼註解應該用來指出程式碼無法說明的內容。開發人員通常會更新其程式碼，但忘了更新程式碼註解。最好是為更高層級的構想使用註解，而不是加入個別程式碼行運作方式的相關註解。

準備您的撰寫程式碼環境

本課程模組包含練習，引導您完成建置和執行範例程式碼的程式。建立您使用 Visual Studio Code 做為開發環境來完成這些活動。針對這些活動使用 Visual Studio Code，可協助您更熟悉在全球專業人員使用的開發人員環境中撰寫及執行程式碼。

打開 Visual Studio Code。

您可以使用 Windows [開始] 功能表 (或另一個作業系統的對等資源) 來開啟 Visual Studio Code。
在 Visual Studio Code 的 [檔案] 功能表上，選取 [開啟資料夾]。
在 [開啟資料夾] 對話方塊中，瀏覽至 Windows Desktop 資料夾。

如果您在不同的資料夾位置中保留程式碼專案，您可以改用該資料夾位置。針對本訓練，請務必使用容易找到並記住的位置。
在 [開啟資料夾] 對話方塊中，選取 [選取資料夾]。

如果您看到詢問您是否信任作者的安全性對話方塊，請選取 [是]。
在 Visual Studio Code 的 [終端] 功能表上，選取 [新增終端]。

請注意，終端面板中的命令提示字元會顯示目前資料夾的資料夾路徑。例如：
```
C:\Users\someuser\Desktop>
```
注意

如果您是在自己的電腦上工作，而不是在沙箱或託管環境中工作，且您已完成此 C# 系列中的其他 Microsoft Learn 課程模組，您可能已針對程式碼範例建立專案資料夾。如果是這種情況，您可以略過下一個步驟，這個步驟會用來在 TestProject 資料夾中建立主控台應用程式。
在終端命令提示字元中，若要在指定的資料夾中建立新的主控台應用程式，請輸入 dotnet new console -o ./CsharpProjects/TestProject，然後按 Enter 鍵。

這個 .NET CLI 命令會使用 .NET 程式範本，在指定的資料夾位置中建立新的 C# 主控台應用程式專案。這個命令會為您建立 CsharpProjects 和 TestProject 資料夾，並使用 TestProject 做為 .csproj 檔案的名稱。
在 [總管] 面板中，展開 CsharpProjects 資料夾。

您應該會看到 TestProject 資料夾和兩個檔案：名為 Program.cs 的 C# 應用程式檔案，以及名為 TestProject.csproj 的 C# 專案檔。
在 [總管] 面板中，若要在 [編輯器] 面板中檢視程式碼檔案，請選取 [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.");
*/
```
如果您需要撰寫長註解或移除多行程式碼，區塊註解就很適合。區塊註解會在程式碼開頭使用 /*，並在結尾使用 */。使用區塊註解是停用三行或以上的程式碼最快速且最簡單的方式。

將現有程式碼取代為下列程式碼：

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# 概念。您不一定要了解程式碼的作用，才能理解註解如何協助讀者了解程式碼的用途。

花一點時間查看您是否可以推論出程式碼的用途。

如果有註解，您或許能夠了解程式碼的作用 (假設註解會正確地描述目前的狀態，並在程式碼更新時更新)。但您是否可以猜出此程式碼存在的原因？如果程式碼檔案頂端有一些說明可提供一些內容並描述其用途，這不是很實用嗎？
考慮如何改善註解。

請注意，這些註解有兩個主要問題：
- 程式碼註解不必要地說明個別程式碼行的明顯功能。這些會被視為低品質的註解，因為它們只會說明 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 Class Library 運作方式的程式碼註解。
在暫時嘗試替代解決方案時，請使用程式碼註解，直到您準備好要認可到新的程式碼解決方案為止，此時可以刪除舊的程式碼。
永遠不要信任註解。在許多變更和更新之後，它們可能不會反映程式碼的目前狀態。

繼續

練習 - 建立有效的程式碼註解

什麼是程式碼註解？

準備您的撰寫程式碼環境

建立和使用程式碼註解

概括回顧

意見反應