编辑“︁C Sharp 注释”︁（章节）

= C#注释 =

'''注释'''是C#代码中用于解释代码功能、逻辑或提供其他信息的文本片段。编译器会忽略注释内容，因此注释不会影响程序执行。良好的注释习惯能显著提升代码可读性和可维护性，是团队协作和后期维护的重要工具。

== 注释类型 ==
C#支持三种注释方式：

=== 单行注释 ===
以双斜杠 <code>//</code> 开头，直到行尾的内容都会被忽略。

<syntaxhighlight lang="csharp">
// 这是单行注释
int x = 5; // 声明并初始化变量x
</syntaxhighlight>

=== 多行注释 ===
以 <code>/*</code> 开始，以 <code>*/</code> 结束，可跨越多行。

<syntaxhighlight lang="csharp">
/* 这是多行注释
   可以包含多行内容
   常用于代码块说明 */
int y = 10;
</syntaxhighlight>

=== XML文档注释 ===
以 <code>///</code> 开头，用于生成API文档，支持特殊标签。

<syntaxhighlight lang="csharp">
/// <summary>
/// 计算两个数的和
/// </summary>
/// <param name="a">第一个加数</param>
/// <param name="b">第二个加数</param>
/// <returns>两数之和</returns>
public int Add(int a, int b)
{
    return a + b;
}
</syntaxhighlight>

== 注释最佳实践 ==

=== 何时使用注释 ===
* 解释复杂算法或业务逻辑
* 说明代码的意图（而不仅是代码在做什么）
* 标记待办事项（TODO）或已知问题（FIXME）
* 公共API的文档说明

=== 应避免的情况 ===
* 描述显而易见的代码
* 过时的注释（与代码不同步）
* 过多的注释（代码本身应尽可能自解释）

== 实际应用示例 ==

=== 算法说明 ===
<syntaxhighlight lang="csharp">
// 使用欧几里得算法计算最大公约数
// 算法原理：gcd(a,b) = gcd(b, a mod b)
public static int GCD(int a, int b)
{
    while (b != 0)
    {
        int temp = b;
        b = a % b;
        a = temp;
    }
    return a;
}
</syntaxhighlight>

=== 团队协作标记 ===
<syntaxhighlight lang="csharp">
// TODO: 需要优化数据库查询性能 - 张三 2023-05-01
public List<Product> GetProducts()
{
    // 当前实现会加载所有字段
    return dbContext.Products.ToList();
}
</syntaxhighlight>

== XML文档注释详解 ==
XML文档注释可通过编译器生成正式的API文档。常用标签包括：

{| class="wikitable"
|-
! 标签 !! 描述
|-
| <code><summary></code> || 类型或成员的简要说明
|-
| <code><remarks></code> || 详细说明
|-
| <code><param></code> || 方法参数说明
|-
| <code><returns></code> || 返回值说明
|-
| <code><exception></code> || 可能抛出的异常
|-
| <code><example></code> || 使用示例
|}

示例：
<syntaxhighlight lang="csharp">
/// <summary>
/// 计算圆的面积
/// </summary>
/// <param name="radius">圆的半径，必须大于0</param>
/// <returns>圆的面积</returns>
/// <exception cref="ArgumentException">当radius小于等于0时抛出</exception>
/// <example>
/// <code>
/// double area = CalculateCircleArea(5.0);
/// </code>
/// </example>
public double CalculateCircleArea(double radius)
{
    if (radius <= 0)
        throw new ArgumentException("半径必须大于0", nameof(radius));
    
    return Math.PI * radius * radius;
}
</syntaxhighlight>

== 注释与代码质量 ==
研究表明良好的注释习惯可以：
* 减少代码理解时间
* 降低维护成本
* 提高团队协作效率

<mermaid>
pie
    title 代码维护时间分配
    "理解代码" : 45
    "实际修改" : 25
    "测试验证" : 30
</mermaid>

== 数学公式示例 ==
当注释涉及数学概念时，可以使用公式说明：

圆的面积公式：<math>A = \pi r^2</math>

线性回归的代价函数：<math>J(\theta) = \frac{1}{2m} \sum_{i=1}^m (h_\theta(x^{(i)}) - y^{(i)})^2</math>

== 总结 ==
* 注释是代码的重要组成部分，但不是代码质量差的补救措施
* 优先编写清晰、自解释的代码，只在必要时添加注释
* XML文档注释是.NET生态中的重要工具
* 保持注释与代码同步，过时的注释比没有注释更糟糕

良好的注释习惯是专业开发者的标志之一，它能显著提升代码的可维护性和团队协作效率。

[[Category:编程语言]]
[[Category:C Sharp]]
[[Category:C Sharp 基础]]