C# 函数注释实战：如何在函数调用处通过鼠标悬停查看注释

1次阅读

共计 2024 个字符，预计需要花费 6 分钟才能阅读完成。

刚开始用 C# 的时候，最让我头疼的就是调用别人写的函数时，完全不知道这个函数是干嘛用的。特别是接手老项目时，经常看到这样的代码：

public int Calc(int a, int b)
{return a + b;}

这个 Calc 到底计算什么？
参数 a 和 b 有没有取值范围限制？
返回值有没有特殊含义？

这种没有注释的函数就像黑盒子，每次调用都得翻源码，效率特别低。更可怕的是，有些同事写的函数名和实际功能完全不搭边（比如叫 GetData 的函数居然会删除数据库记录）。

C# 提供了官方的 XML 文档注释方案，用三个斜杠 /// 就能生成标准的注释模板。最常用的几个标签：

/// <summary>
/// 计算两个数的和（这是最基础的注释）/// </summary>
/// <param name="a"> 第一个加数，必须大于 0 </param>
/// <param name="b"> 第二个加数，不能超过 100</param>
/// <returns> 两数之和，如果超过 int 上限会抛出溢出异常 </returns>
/// <exception cref="OverflowException"> 当计算结果溢出时抛出 </exception>
/// <example>
/// 示例代码：/// <code>
/// var result = Calc(10, 20); // 返回 30
/// </code>
/// </example>
public int Calc(int a, int b)
{checked { return a + b;}
}

<summary>：函数功能概述（必填）
<param>：参数说明，name 属性必须和参数名一致
<returns>：返回值说明
<exception>：可能抛出的异常
<example>：使用示例（强烈建议加上）

在 Visual Studio 中需要开启 XML 文档生成功能：

右键项目 → 选择 ” 属性 ”
切换到 ” 生成 ” 标签页
勾选 ”XML 文档文件 ” 选项（保持默认路径即可）
如果是 Debug/Release 分开配置，记得两个模式都要勾选

（注：此处应为配置截图）

来看个复杂点的例子，包含泛型和方法重载：

/// <summary>
/// 将对象序列化为 JSON 字符串
/// </summary>
/// <typeparam name="T"> 必须是可序列化的类型 </typeparam>
/// <param name="obj"> 待序列化对象，不能为 null</param>
/// <param name="indented"> 是否格式化输出，默认 false</param>
/// <returns>JSON 格式字符串 </returns>
/// <exception cref="ArgumentNullException"> 当 obj 为 null 时抛出 </exception>
public static string ToJson<T>(T obj, bool indented = false) 
{if (obj == null) throw new ArgumentNullException(nameof(obj));
    return JsonSerializer.Serialize(obj, new JsonSerializerOptions {WriteIndented = indented});
}

/// <summary>
/// 将对象序列化为 JSON 字符串（简化版）/// </summary>
public static string ToJson<T>(T obj) => ToJson(obj, false);

调用时效果：

（注：此处应为效果截图）

注释不更新 ：修改注释后要重新编译项目才会生效
中文乱码 ：在项目文件的 <PropertyGroup> 里加上 <CodePage>65001</CodePage>
第三方库看不到注释 ：确保引用的 NuGet 包包含.xml 文档文件
标记无效 ：检查标签拼写是否正确，比如 <param> 写成 <params> 就不会生效

用 Sandcastle 工具可以生成漂亮的 CHM 文档：

安装 Sandcastle Help File Builder
新建项目，添加你的程序集和 XML 文档
选择文档风格（推荐 VS2013 风格）
点击生成，就能得到可搜索的离线帮助文档

<!-- 示例：.shfbproj 配置文件片段 -->
<DocumentationSources>
    <DocumentationSource sourceFile="bin\Debug\MyLib.dll" 
                          xmlFile="bin\Debug\MyLib.xml" />
</DocumentationSources>

自从团队强制要求写 XML 注释后，我们的代码可读性提高了至少 50%。新人接手项目时，直接通过智能提示就能理解大部分 API 的用法，再也不用一边看代码一边骂前任开发者了。

最后的小建议：写 <example> 时最好包含正反两种用例，比如参数为 null 时应该怎么处理，这样调用方就能一眼明白边界条件。

正文完