5. 注释、代码约定与命名规范

本节目标：用对三种注释，掌握 PascalCase / camelCase 命名约定，写出别人也读得懂的代码。

能跑的代码只是第一步。真正值钱的代码，是半年后你自己还能看懂的代码。这一章讲两件”软实力”：注释和命名。它们不改变程序行为，却决定了代码能不能被维护、被信任。

为什么注释很重要

编译器会忽略注释（comment），但人会读。注释用来解释”为什么这么写”，而不是”写了什么”——后者 good 代码本身就能表达。

新手常犯两个极端：要么一行注释不写，过两周看不懂；要么每行都写”这是赋值为 1”，纯属噪音。

Tip

一条好注释回答的是”意图”。比如 // 余额不足时拒绝交易，比 // 判断 balance < 0 有用得多。前者说清业务原因，后者只是把代码翻译回中文，等于没说。

单行注释

两个斜杠开头，到行尾结束，最常用：

namespace CSharpDemo;

int age = 18; // 用户年龄，单位岁
// 下面判断是否成年
bool isAdult = age >= 18;

// 后面的内容编译器当空气处理。适合在某一行旁边或上方做简短说明。

多行注释

需要写一大段说明时，用 /* 和 */ 包起来，中间可跨多行：

/*
 * 这个方法计算订单总价。
 * 含税，但不含运费。
 * 后续可能要抽成独立服务。
 */
decimal total = 9.99m * 3;

多行注释不能嵌套——里面再写 /* 会出问题。它适合临时屏蔽一整段代码，或写较完整的设计说明。

Note

想临时不让某段代码参与编译，多行注释很方便。但正式排错更推荐用 IDE 的”注释快捷键”，比手敲 /* */ 安全，且能一键取消注释。

XML 文档注释

三个斜杠 /// 开头的是 XML 文档注释（XML documentation comment）。它专门写给方法、类、属性，能被工具提取成帮助文档：

/// <summary>
/// 计算两个整数的和。
/// </summary>
/// <param name="a">第一个加数</param>
/// <param name="b">第二个加数</param>
/// <returns>两数相加的结果</returns>
int Add(int a, int b) => a + b;

写好后，别处调用 Add 时，编辑器会弹出你写的说明。团队开发里这是基本礼仪：公开的方法都该有 /// <summary>。

XML 注释还能写更多

除了 summary / param / returns，还有几个常用标签：

<remarks>：补充说明、注意事项，比 summary 更细。
<exception>：说明这个方法可能抛出什么异常。
<example>：给出调用示例。

/// <summary>
/// 把字符串解析成整数。
/// </summary>
/// <param name="text">要解析的文字</param>
/// <returns>解析出的整数</returns>
/// <exception cref="FormatException">当 text 不是合法数字时抛出</exception>
/// <example>ParseNumber("42") 返回 42</example>
int ParseNumber(string text) => int.Parse(text);

这些标签会被编译进一份 XML 文档文件（项目开启生成文档时），别人引用你的库就能在编辑器里看到完整提示。初学不必全用，但 summary 是底线。

Tip

注释里还有些约定俗成的前缀标记：// TODO 表示”这儿还得做”，// HACK 表示”临时凑合、需重做”，// NOTE 表示”注意点”。它们不被编译器执行，但人一看就懂，团队协作时很常见。

命名约定：大小写有讲究

C# 有一套约定俗成的命名法，遵守了，代码立刻”像内行写的”。核心是两种大小写：

PascalCase（帕斯卡命名）：每个单词首字母大写，如 Person、Calculator、StudentScore。用于类名、方法名、属性名、公开字段。
camelCase（驼峰命名）：首个单词全小写，后面每个首字母大写，如 name、totalCount、orderPrice。用于局部变量和参数。

为什么分两套？因为一眼就能区分”这是类型/成员”还是”这是临时变量”，眼睛扫过去就有层级感，不用脑补。

具体怎么用

举个例子，把约定落地：

namespace CSharpDemo;

class Student
{
    public string Name { get; set; }   // 属性：PascalCase
    public int Score { get; set; }     // 属性：PascalCase

    public void PrintInfo()            // 方法：PascalCase
    {
        string greeting = "成绩：";    // 局部变量：camelCase
        Console.WriteLine($"{greeting}{Name} {Score}");
    }
}

类名 Student、属性 Name、方法 PrintInfo 都是 PascalCase；局部变量 greeting 是 camelCase。一眼就能区分”这是类型/成员”还是”这是临时变量”。

Tip

接口（interface）命名习惯以大写 I 开头，如 IEnumerable、IDisposable。看到 I 前缀，就知道它是接口。后面章节会讲。常量（const）也用 PascalCase，如 const int MaxRetry = 3;。

命名长度：别太短也别太长

命名有个度：太短看不懂，太长敲得累、还模糊重点。

太短：int d; 没人知道 d 是天还是距离。
太长：int theNumberOfDaysSinceUserRegistered; 啰嗦到影响阅读。
刚好：int dayCount;。

原则：在”能看懂”和”不啰嗦”之间取平衡。作用域越小（比如循环里的临时变量 i），名字可以越短；作用域越大（公开属性、方法），名字越要表意。

布尔变量用 Is/Has/Can 前缀

表示”是/否”的变量或属性，用 Is / Has / Can 开头，读起来像一句问话，意图最清楚：

bool isActive = true;     // 是否激活
bool hasPermission = false; // 是否有权限
bool canEdit = true;      // 能否编辑

这样 if (isActive) 读起来就是”如果是激活的”，天然顺口，比 if (flag) 强太多。

可读性的几条原则

名字要表意：int d 不如 int dayCount；List<string> n 不如 List<string> names。
一行一件事：别把三四个操作挤在一行，分开更易读也易调试。
缩进要一致：用空格或 Tab 统一缩进，体现代码层级。
方法别太长：一个方法最好不超过一屏，过长就拆小方法。

Note

本教程复用几个固定示例实体，方便你形成记忆：Person(Name, Age)、Student(Id, Name, Score)、Product(Id, Name, Price)、Calculator。看到它们，定义都一致。

注释会被编译进程序吗

不会。注释在编译阶段就被丢弃，不影响运行速度和最终文件大小。所以放心写注释，别担心”写了会变慢”。但反过来，注释再多也救不了烂逻辑——它只解释，不改正代码。

有个常见误区：把代码逻辑全写进注释，正文却空着。那不是注释，是”用注释代替代码”，是本末倒置。注释永远只补充”为什么”，不重复”是什么”。

命名歪了会怎样

C# 编译器对命名没有强制（除了不能用关键字）。你写成 class x、int a1 也能编译。但坏命名有三宗罪：

可读性差：一周后你自己都忘了 a1 是啥。
易出 bug：含义模糊的变量容易被误用，比如把”总价”和”数量”的短名搞混。
协作受阻：别人接手你的代码要花双倍时间猜意图。

所以约定不是束缚，是给团队（和未来的你）的善意。PascalCase 给类型/成员、camelCase 给变量，这个习惯一旦养成，看谁的代码都顺。

Note

有些团队用工具（如编辑器分析器）强制命名规范，写错就画波浪线提醒。初学阶段先靠自觉，等进了团队自然会统一。

注释的边界：何时不写

好注释讲”为什么”，但有几种情况宁可少写：

代码本身已足够清楚：i++ 旁边写”i 加一”纯属噪音。
会随代码过时的描述：改了逻辑却忘了改注释，反而误导人。
把注释当 TODO 永久搁置：真要改就改，别只留一句”以后优化”。

记住一句金科玉律：代码表达’做什么’，注释解释’为什么’。 两者分工清晰，代码才干净。

常见疑问解答

问：注释写越多越安全吗？ 恰恰相反。注释太多会掩盖代码本身的问题，且容易和代码不同步（改了代码忘了改注释）。好代码优先靠清晰命名和结构简单表达，注释只补”为什么”。

问：变量名用拼音可以吗？ 可以跑，但不推荐。英文命名是国际协作的默认，搜索引擎、文档、同事都更友好。实在想不出英文，先用对，后续逐步替换。本教程统一用英文命名。

问：方法名一定要动词开头吗？ C# 习惯方法名表达”动作”，如 CalculateTotal、PrintInfo。属性名则是名词（如 Name、Price）。这个约定让 x.PrintInfo() 读起来像句子，很自然。

问：常量怎么命名？ const 常量也用 PascalCase，如 const decimal TaxRate = 0.13m;。和静态只读字段（static readonly）一样大写开头，一眼能和局部变量区分。

要点速记

注释讲”为什么”，不重复”是什么”；代码表达做什么，注释解释为什么。
三种注释：单行 //、多行 /* */、XML ///（可含 remarks/exception/example）。
PascalCase 给类/方法/属性/常量，camelCase 给变量/参数。
名字表意优先，布尔用 Is/Has/Can 前缀，缩进一致，方法别太长。

动手练一练

给一个 Calculator 类写 XML 文档注释，说明它负责四则运算，并为 Add 方法的参数和返回值各写一句说明，再加一条 <exception>。
把下面的变量名改成符合约定的写法：int X1;（用户年龄）、string str_name;（用户名）。提示：局部变量用 camelCase。
找一段你之前写的代码，给每个方法补上 /// <summary>，体会文档注释在编辑器里弹出的效果。

小结与下一步

注释讲”为什么”，命名讲”像不像 C#“。三种注释各有所长，PascalCase 给类型与成员、camelCase 给变量与参数，布尔用 Is/Has/Can 前缀。这些习惯越早养成越省事——它们不让你写得更对，但让你写得被信任。

下一章换个实用技能：当程序不对劲时，怎么用调试（debug）把它揪出来。