掌握 C# 注释：类型、最佳实践与 XML 文档注释

C# 注释

本文介绍 C# 注释的三种风格、使用原因及在程序中有效使用的方法。

注释是可读代码的生命线。它们是人类可读的标注，用于解释意图、阐明复杂逻辑、记录设计决策。编译器完全忽略注释，因此不影响运行时性能。

根据微软官方文档，C# 支持三种主要注释风格：

1. 单行注释 (//)
2. 多行注释 (/* */)
3. XML 文档注释 (///)

单行注释

单行注释以双斜杠 // 开头，延伸至行尾。// 后的所有内容被编译器忽略。

int a = 5 + 7; // Adding 5 and 7

此处 Adding 5 and 7 即为注释。

示例 1：使用单行注释

// Hello World Program
using System;
namespace HelloWorld {
    class Program {
        public static void Main(string[] args) // Execution starts from Main method
        {
            // Prints Hello World
            Console.WriteLine("Hello World!");
        }
    }
}

上述程序包含三条单行注释：

// Hello World Program
// Execution starts from Main method
// Prints Hello World

虽可将注释置于代码同行，但最佳实践是单独占行，避免混乱。

多行注释

多行注释以 /* 开始，以 */ 结束，可跨越多行，适合块级解释或临时禁用代码块。

示例 2：使用多行注释

/* This is a Hello World Program in C#.
This program prints Hello World. */
using System;
namespace HelloWorld {
    class Program {
        public static void Main(string[] args) {
            /* Prints Hello World */
            Console.WriteLine("Hello World!");
        }
    }
}

程序包含两个多行注释：

/* This is a Hello World Program in C#. This program prints Hello World. */
/* Prints Hello World */

单个 /* … */ 块在需要简洁时也可替代单行注释。

XML 文档注释

XML 文档注释以三斜杠 /// 开头，允许开发者在代码中嵌入结构化元数据。这些注释可被 Visual Studio 等工具提取，生成外部 XML 文档文件，供 IDE 提供 IntelliSense 提示、文档生成器使用。

若不熟悉 XML，可参考 什么是 XML？。

示例 3：使用 XML 文档注释

/// <summary>
/// This is a hello world program.
/// </summary>
using System;
namespace HelloWorld {
    class Program {
        public static void Main(string[] args) {
            Console.WriteLine("Hello World!");
        }
    }
}

示例中的 XML 注释为：

/// <summary>
/// This is a hello world program.
/// </summary>

生成的 XML 文件类似：

<?xml version="1.0"?>
<doc>
<assembly>
<name>HelloWorld</name>
</assembly>
<members>
</members>
</doc>

深入了解请访问 XML 文档注释。

正确使用注释

有效注释应阐明意图而不混淆代码。过度注释会掩盖逻辑，注释不足则增加维护难度。

看这个例子：

// Prints Hello World
Console.WriteLine("Hello World");

此处注释多余，代码已自解释。应使用注释来：

• 解释非显而易见的算法或业务逻辑。
• 标注假设、边界情况或潜在陷阱。
• 简述代码块目的，聚焦“为什么”而非“怎么做”。

记住：简洁、有目的的注释是专业代码库的标志。