练习 - 创建有效的代码注释

  • 13 分钟

在本练习中，你将向代码添加注释并暂时禁止某些代码行进行编译。 然后，你将了解 C# 编译器如何理解空格，学习如何使用空格来提高代码的可读性。

什么是代码注释？

代码注释是一条指令，用于指示编译器忽略当前行中代码注释符号后面的一切内容。

// This is a code comment!

刚开始这似乎没什么作用，但是在以下三种情况非常有用：

  • 当你想记下一段代码的意图时。 当你编写一组极具挑战性的代码指令时，包含描述用途或思考过程的代码注释可能会很有帮助。 将来的你会感谢自己。
  • 当你想暂时删除应用程序中的代码，以尝试其他方法，但不确信新想法是否有用时。 可以注释掉代码，编写新代码，一旦你确定新代码会按预期方式运行时，就可安全地删除旧代码（注释代码）。
  • 添加类似于 TODO 的消息，以提醒自己稍后查看特定的代码段。 虽然你应该谨慎地使用这种方法，但它很有用。 当阅读到引起你关注的代码行时，你可能正在处理另一项功能。 你可以对其进行标记以便稍后调查，而不是忽略关注的新代码行。

注意

应使用代码注释来说明代码无法说明的内容。 通常，开发者会更新其代码，但忘记更新代码注释。 最好使用注释来描述更高级别的想法，请勿添加关于单个代码行如何工作的注释。

准备编码环境

本模块包含一些练习，它们将指导你完成生成和运行示例代码的过程。 建议使用 Visual Studio Code 作为开发环境来完成这些活动。 使用 Visual Studio Code 来完成这些活动将帮助你在供全球专业人员使用的开发人员环境中更舒适地编写和运行代码。

  1. 打开 Visual Studio Code。

    可以使用 Windows“开始”菜单（或等效资源 [对于其他 OS]）打开 Visual Studio Code。

  2. 在 Visual Studio Code 的“文件”菜单上，选择“打开文件夹”。

  3. 在“打开文件夹”对话框中，导航到 Windows“桌面”文件夹。

    如果使用了其他文件夹位置来保存代码项目，可以改用该文件夹位置。 对于此训练，重要的是要有一个容易找到和记住的位置。

  4. 在“打开文件夹”对话框中，选择“选择文件夹”。

    如果看到一个询问是否信任作者的安全对话框，请选择“是”。

  5. 在 Visual Studio Code 的“终端”菜单上，选择“新终端”。

    请注意，“终端”面板中的命令提示符显示当前文件夹的文件夹路径。 例如：

    C:\Users\someuser\Desktop>

    注意

    如果你在自己的电脑上工作，而不是在沙盒或托管环境中工作，并且你已经完成此 C# 系列中的其他 Microsoft Learn 模块，那么你可能已经为代码示例创建了一个项目文件夹。 如果是这种情况，可以跳过下一步，该步骤用于在 TestProject 文件夹中创建控制台应用。

  6. 在终端命令提示符下，若要在指定文件夹中创建新的控制台应用程序，请输入以下提示：

    dotnet new console -o ./CsharpProjects/TestProject

    此 .NET CLI 命令使用 .NET 程序模板在指定文件夹位置创建新的 C# 控制台应用程序项目。 该命令会自动创建 CsharpProjects 和 TestProject 文件夹，并使用 TestProject 作为 .csproj 文件的名称。

    如果显示一条消息，告知文件已存在，请继续执行后续步骤。 你将重复使用现有的项目文件。

  7. 在 EXPLORER 视图中，展开 CsharpProjects 文件夹。

    应会看到 TestProject 文件夹和两个文件：一个名为Program.cs的 C# 程序文件和一个名为 TestProject.csproj 的 C# 项目文件。

  8. 在 Visual Studio Code 的“文件”菜单上，选择“打开文件夹”。

  9. 在 “打开文件夹 ”对话框中，选择 CsharpProjects 文件夹，然后选择“ 选择文件夹”。

  10. 在 EXPLORER 视图中，展开 TestProject 文件夹，然后选择 Program.cs。

  11. 删除现有代码行。

    在本模块中，你将使用此 C# 控制台项目来创建、生成和运行代码示例。

  12. 关闭“终端”面板。

创建和使用代码注释

在此任务中，你将创建和删除各种类型的代码注释。

  1. 在 Visual Studio Code 编辑器面板中，输入以下代码：

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

  2. 若要使用代码注释和修订来修改代码，请按如下所示更新代码：

    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.");

  3. 花点时间检查一下你的注释和代码更新。

    请注意，代码注释用于记录可能做出的更改，并用于在你测试新消息时暂时禁用旧消息。 下一步是测试更新。 如果你对新代码感到满意，可以安全地删除注释掉的旧代码。在你确信你已准备好永久删除工作代码之前，这是一种更安全、更有条理的修改工作代码的方法。

  4. 在 Visual Studio Code 的“文件”菜单上，单击“保存”。

  5. 在 EXPLORER 视图中，若要在 TestProject 文件夹位置打开终端，请右键单击 TestProject，然后选择“ 在集成终端中打开”。

  6. 在终端命令提示符处，请键入 dotnet run，然后按 Enter。

    应会看到以下输出：

    Bob purchased 7 widgets.

    同样，如果你对更新感到满意，请删除注释掉的旧代码。

  7. 删除代码注释。

    你的代码应与以下内容一致：

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

  8. 若要应用注释掉多行的块注释，请按如下所示更新代码：

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

    如果需要编写长注释或移除许多代码行，块注释是很好的选择。 块注释在代码开头使用 /*，在末尾使用 */。 使用块注释是禁用三个或更多代码行的最快速、最简单的方式。

  9. 将现有代码替换为以下内容：

    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# 概念。 无需为了理解注释如何帮助读者了解代码用途而去了解代码所执行的操作。

  10. 花一点时间看看你能否弄清楚代码的用途。

    在提供注释的情况下，你也许能够明白代码所执行的操作（假设注释准确地说明了当前状态并随着代码一起更新）。 但你能猜一猜此代码为什么存在吗？ 如果代码文件的顶部有一些解释提供了一些上下文并描述了其用途，这不是很有帮助吗？

  11. 考虑如何改进注释。

    请注意，这些注释主要存在两个问题：

    • 代码注释不必要地解释了单独代码行的明显功能。 这些被视为低质量的注释，因为它们只解释了 C# 或 .NET 类库的方法如何工作。 如果读者不熟悉这些内容，他们可以使用 learn.microsoft.com 或 IntelliSense 来查阅。
    • 代码注释未提供代码所解决问题的任何上下文。 这些被视为低质量的注释，因为读者无法了解此代码的用途，尤其是在涉及到更大的系统时。

  12. 移除现有注释。

    你的代码应与以下内容一致：

    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);
}

    请注意，代码变得更有条理了。

  13. 若要添加注释来说明代码的大致用途，请按如下所示更新代码：

    /*
  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 类库如何工作的代码注释。
  • 暂时尝试替代解决方法时，请使用代码注释，直至你已准备提交新的代码解决方案，此时可以删除旧代码。
  • 不要完全相信注释。 在进行许多更改和更新之后，它们可能不会反映代码的当前状态。