注释、关键字、标识符与命名规范

一、学习目标

完成本章后，你应该能够：

能够正确书写并区分单行注释、多行注释和文档注释。
能够解释 Java 规范中的“注释形式”与教学中“三种注释”的区别。
能够使用 Javadoc 文档注释描述类、方法、参数、返回值等程序元素。
能够解释什么是关键字，并区分保留关键字（Reserved Keyword）与上下文关键字（Contextual Keyword）。
能够正确判断一个名称是否属于合法的 Java 标识符（Identifier）。
能够区分“语法上合法的名称”和“工程上推荐的名称”。
能够按照 Java 常见命名规范为包、类、方法、变量和常量命名。
能够识别低质量注释、错误命名和失效注释，并进行重构。

二、核心知识

2.1 什么是注释

注释（Comment）是写在源代码中，用来帮助人理解程序的说明性内容。

例如：

int age = 18; // 用户年龄

其中：

// 用户年龄

就是注释。

注释最主要的读者并不是计算机，而是：

当前的开发者；
未来的自己；
团队中的其他程序员；
API 的使用者；
代码维护者。

所以注释的核心价值是：

帮助人理解代码的意图、原因、边界和使用方法。

2.2 注释会不会被程序执行

不会。

Java 源代码首先需要经过编译器处理。

从词法结构角度看，Java 编译器会识别：

空白；
注释；
标识符；
关键字；
字面量；
分隔符；
运算符。

其中注释在形成 Java 语法 Token 之前就会被忽略。

例如：

public class CommentDemo {

    public static void main(String[] args) {
        int age = 18;

        // age = 100;

        System.out.println(age);
    }
}

被注释掉的：

age = 100;

不会作为普通 Java 语句参与程序执行。

因此：

注释不会改变正常程序的执行逻辑。

当然，如果你错误地添加或者删除注释符号，可能导致原本应该参与编译的代码被注释掉，或者造成源代码无法正确解析。

2.3 Java 教学中的三种注释

Java 入门教学通常把注释分成：

单行注释；
多行注释；
文档注释。

2.4 单行注释

语法：

// 注释内容

从：

//

开始，一直到当前行结束，后面的内容都属于注释。

例如：

int age = 18; // 学生年龄

也可以独占一行：

// 计算订单最终价格
double finalPrice = 99.9;

单行注释适合：

简短说明；
临时解释；
TODO；
解释某个特殊业务规则。

例如：

// TODO 后续增加参数合法性校验

2.5 多行注释

语法：

/*
    注释内容
    可以跨越多行
*/

例如：

/*
    当前案例仅用于演示 Java 基础语法，
    暂时不考虑用户输入异常。
*/
public class Demo {
}

多行注释适合：

一段较长的说明；
临时注释连续多行内容；
某些不适合单行表达的解释。

2.6 多行注释不能嵌套

例如：

/*
    外层注释开始

    /*
        内层注释
    */

    外层注释结束
*/

不能按照：

外层
    内层
外层

这样的结构理解。

Java 的传统注释：

/*
...
*/

会在遇到符合规则的结束符：

*/

时结束。

所以：

Java 多行注释不支持真正的嵌套。

开发时如果大量使用：

/*
    ...
*/

去临时屏蔽大段本身已经包含多行注释的代码，就可能遇到结构问题。

现代 IDE 中通常可以使用：

Ctrl + /

给多行代码分别添加：

//

从而避免这种嵌套问题。

2.7 文档注释

教学中常见的第三种形式是：

/**
 * 文档注释
 */

例如：

/**
 * 表示一个学生。
 */
public class Student {
}

或者：

/**
 * 计算两个整数的和。
 *
 * @param a 第一个整数
 * @param b 第二个整数
 * @return 两个整数的和
 */
public static int sum(int a, int b) {
    return a + b;
}

这种形式通常称为：

文档注释（Documentation Comment / Javadoc Comment）

它可以被：

javadoc

工具识别，并用于生成 API 文档。

2.8 为什么规范说“两种注释”，教程却说“三种

这是一个很容易产生疑问的地方。

从《Java Language Specification》的词法结构来看，Java 定义两类 Comment：

// ...

和：

/* ... */

而：

/**
 * ...
 */

从 Java 语言的词法角度，本质上仍然属于：

/* ... */

这一类传统注释。

但是：

/**
...
*/

具有特殊格式，可以被标准：

javadoc

工具识别为 Documentation Comment。

因此：

语言词法层面
├── // ...
└── /* ... */

教学 / Javadoc 使用层面
├── 单行注释
├── 多行注释
└── 文档注释 /** ... */

所以说：

“Java 教学中有三种常见注释写法”

没有问题。

但如果问：

“JLS 的词法语法正式定义了几类 Comment？”

答案对应的是规范层面的两类。

2.9 文档注释应该放在哪里

文档注释必须与被描述的程序元素建立明确关系。

常见位置包括：

module；
package；
class；
interface；
constructor；
method；
field。

例如：

/**
 * 用户服务。
 */
public class UserService {
}

方法：

/**
 * 计算 BMI。
 *
 * @param weight 体重，单位 kg
 * @param height 身高，单位 m
 * @return BMI 数值
 */
public static double calculateBMI(double weight, double height) {
    return weight / (height * height);
}

如果把文档注释放在普通方法体内部：

public static void test() {

    /**
     * 这里不是在给一个声明生成 API 文档
     */
    int age = 18;
}

标准 Javadoc 不会把它当作一个正常声明对应的 API 文档注释。

2.10 常见 Javadoc 标签

当前只需要认识几个高频标签。

`@param`

描述参数：

/**
 * @param age 用户年龄
 */

`@return`

描述返回值：

/**
 * @return 计算后的价格
 */

`@throws`

描述方法可能抛出的异常：

/**
 * @throws IllegalArgumentException 参数非法时抛出
 */

异常将在后面的章节系统学习。

`@deprecated`

描述某个 API 已经不推荐继续使用。

通常还会配合：

@Deprecated

注解。

这部分将在后续注解章节进一步理解。

2.11 使用 javadoc 生成文档

假设存在：

/**
 * 数学工具类。
 */
public class MathUtils {

    /**
     * 计算两个整数的和。
     *
     * @param a 第一个整数
     * @param b 第二个整数
     * @return 两个整数之和
     */
    public static int add(int a, int b) {
        return a + b;
    }
}

可以尝试：

javadoc -d docs -encoding UTF-8 MathUtils.java

其中：

javadoc

是 JDK 提供的文档生成工具。

-d docs

表示将生成结果输出到：

docs

目录。

当前阶段不需要记住 Javadoc 的全部标签和复杂配置。

重点是知道：

/** ... */ 可以成为 Java API 文档的源内容。

2.12 注释不是越多越好

错误的学习方式是：

// 定义一个 int 变量 age，然后赋值 18
int age = 18;

// age 加 1
age = age + 1;

// 输出 age
System.out.println(age);

代码本身已经非常清楚。

这些注释只是把代码翻译成中文，并没有提供额外信息。

好的注释应该更多回答：

为什么这样做？

例如：

// 业务规定：未完成实名认证的用户每天最多创建 3 个订单
int dailyOrderLimit = 3;

这个注释解释了：

为什么是 3。

这就比：

// 定义 dailyOrderLimit，值为 3
int dailyOrderLimit = 3;

有价值。

2.13 注释应该解释“Why”，而不仅仅是“What”

代码往往已经能够告诉开发者：

做了什么

注释更适合解释：

为什么这样做

例如：

// 使用 BigDecimal 而不是 double，避免金额计算中的二进制浮点精度问题

这种注释解释的是技术选择原因。

而下面这种：

// 创建 BigDecimal

价值就很有限。

2.14 失效注释比没有注释更危险

假设最初代码：

// 最大重试次数为 3
int maxRetryCount = 3;

后来代码被改成：

// 最大重试次数为 3
int maxRetryCount = 5;

这时注释和代码发生冲突。

维护者会产生疑问：

到底 3 是正确业务规则？
还是 5 是正确业务规则？

因此：

注释必须随着代码一起维护。

如果注释已经失效：

修改；
或删除；

不要让错误注释长期存在。

2.15 什么是关键字

关键字（Keyword）是 Java 语言本身具有特殊语法意义的字符序列。

例如：

public
class
static
void
int
if
else
for
while
return

这些词不能像普通名称一样随意使用。

例如：

int class = 10;

是不合法的。

因为：

class

在 Java 中具有特殊语法意义。

2.16 Java 21 中关键字并不只是传统列表

很多旧 Java 教程会给出类似：

public
class
int
double
if
else
...

这样的关键字表。

随着 Java 语言演进，情况已经更加完整。

Java 21 规范把相关词分为：

Reserved Keyword

和：

Contextual Keyword

2.17 保留关键字

保留关键字（Reserved Keyword）在语言中被保留，不能作为普通 Identifier 使用。

Java 21 中包括：

abstract
assert
boolean
break
byte
case
catch
char
class
const
continue
default
do
double
else
enum
extends
final
finally
float
for
goto
if
implements
import
instanceof
int
interface
long
native
new
package
private
protected
public
return
short
static
strictfp
super
switch
synchronized
this
throw
throws
transient
try
void
volatile
while
_

其中有几个特殊情况。

`const` 和 `goto`

它们被 Java 保留，但目前并没有像：

if
for
class

那样真正承担普通 Java 语法功能。

也就是说：

不能拿来命名，但通常也不会在日常 Java 代码中真正使用。

`strictfp`

它仍然是保留关键字。

但是在现代 Java 中已经被规范标记为：

obsolete

也就是已经没有必要在新代码中继续依赖它来获得过去的浮点语义效果。

`_`

单独一个：

已经不能作为普通 Identifier。

例如：

int _ = 10;

在现代 Java 中不能作为普通变量声明使用。

但是：

int _count = 10;

这里的 _ 是一个更长 Identifier 的组成部分，语法上属于另一种情况。

2.18 上下文关键字

Java 还存在：

上下文关键字（Contextual Keyword）

例如 Java 21 中可以看到：

module
open
requires
exports
opens
uses
provides
to
with
transitive
var
yield
record
sealed
permits
non-sealed
when

它们和传统 reserved keyword 有所不同。

顾名思义：

是否作为关键字解释，取决于它所处的语法上下文。

例如：

record

在声明 record 类型时具有特殊语言意义。

当前阶段不需要背诵全部上下文关键字。

真正需要建立的认识是：

Java 的关键字体系会随着语言发展演进，不能只机械背诵一张十几年前的关键字表。

2.19 `true` 和 `false` 是关键字吗

严格按照 Java Language Specification：

true
false

不是 Keyword。

它们属于：

Boolean Literal

即：

布尔字面量。

所以：

boolean result = true;

其中：

boolean

是关键字。

而：

true

是字面量。

2.20 `null` 是关键字吗

同样：

null

不是 Keyword。

它属于：

Null Literal

所以严格来说：

true
false
null

都不是 Java Keyword。

不过它们同样不能随便作为普通 Identifier。

例如：

int true = 10;

仍然是不合法的。

2.21 什么是标识符

标识符（Identifier）可以简单理解成：

程序员给程序元素起的名称。

例如：

int age = 18;

这里：

age

就是标识符。

再例如：

public class StudentManager {
}

其中：

StudentManager

也是标识符。

以后还会出现：

类名；
接口名；
方法名；
变量名；
参数名；
包中的名称；
泛型类型参数名。

很多程序元素都需要 Identifier。

2.22 标识符可以由什么组成

初学阶段可以建立下面这套规则。

Java Identifier 可以包含：

Java 字母；
Java 数字。

其中第一部分必须符合：

JavaLetter

规则。

Java 的“字母”概念并不只包括：

A-Z
a-z

还基于 Unicode。

因此一些：

中文；
日文；
希腊字母；
其他 Unicode 字符；

也可能成为合法 Identifier。

2.23 数字不能作为标识符开头

例如：

int user2 = 10;

合法。

但是：

int 2user = 10;

不合法。

可以简单记：

Identifier 后面可以出现数字，但不能用普通数字作为第一个字符。

2.24 `_` 和 `$`

从 Java 标识符规则来看：

_
$

具有特殊历史地位。

例如：

int _count = 10;
int $money = 100;

在相应语法条件下可以成为合法 Identifier。

但是工程代码中通常不推荐随意这样命名。

尤其 $：

Java 官方规范明确建议主要留给机械生成的源代码或少量遗留系统兼容场景。

所以：

int userCount;

通常比：

int $userCount;

更合适。

2.25 中文变量名合法吗

例如：

int 年龄 = 18;

从 Java Unicode Identifier 规则来看，可以是合法代码。

但是：

语法合法 ≠ 工程推荐。

大型工程中通常更推荐稳定的英文命名，例如：

int age = 18;

原因包括：

团队协作；
跨语言交流；
搜索方便；
与 Java API 风格保持一致；
工具与生态一致性更好。

所以要学会区分：

Language Rule

和：

Engineering Convention

2.26 标识符区分大小写

Java 是大小写敏感的。

例如：

int age = 18;
int Age = 20;

从名称角度：

age
Age

并不是同一个 Identifier。

同样：

Student
student
STUDENT

也不相同。

但是不要利用这种特性设计容易混淆的名称。

例如：

int userCount;
int UserCount;
int usercount;

虽然可能语法上能够区分，但工程可读性很差。

2.27 合法标识符与好名字是两回事

例如：

int a = 18;

完全合法。

但如果这个变量表示：

用户年龄

那么：

int userAge = 18;

更加清晰。

所以命名要经过两道判断：

第一层：语法是否合法？

第二层：语义是否清晰？

优秀代码不仅要求：

编译器能看懂。

还要求：

人也容易看懂。

2.28 什么是命名规范

命名规范（Naming Convention）不是 Java 编译器强制执行的语法。

例如：

int USERAGE = 18;

可能完全可以编译。

但是按照常见 Java 风格：

int userAge = 18;

更合理。

命名规范主要服务于：

可读性；
一致性；
团队协作；
维护成本。

2.29 类名：UpperCamelCase

Java 类名通常使用：

大驼峰命名法（UpperCamelCase / PascalCase）

例如：

Student
UserService
OrderController
StudentManager

特点：

第一个单词首字母大写；
后续每个单词首字母大写；
通常使用名词或名词短语。

例如：

public class StudentManager {
}

比：

public class studentmanager {
}

更加符合 Java 常见风格。

2.30 方法名：lowerCamelCase

方法名通常采用：

小驼峰命名法（lowerCamelCase）

例如：

run
calculatePrice
getUserName
saveOrder
findStudent

特点：

第一个单词首字母小写；
后面的单词首字母大写。

方法表示行为，所以通常使用：

动词或动词短语。

例如：

saveUser()
calculateTotalPrice()
printMessage()

2.31 变量名：lowerCamelCase

变量通常也使用小驼峰。

例如：

int age;

String userName;

double productPrice;

int studentCount;

变量应该表达：

这个数据是什么。

例如：

double p = 99.9;

不如：

double productPrice = 99.9;

清晰。

2.32 常量名：UPPER_SNAKE_CASE

常量通常使用：

全部大写 + 下划线分隔单词

例如：

MAX_RETRY_COUNT

DEFAULT_PAGE_SIZE

MIN_AGE

PI

典型形式：

static final int MAX_RETRY_COUNT = 3;

static、final 和真正的常量定义会在后续章节学习。

当前先记住命名风格即可。

2.33 包名通常全部小写

Package 名通常：

全小写

例如：

com.xingyu.user

com.xingyu.tutorial

com.xingyu.blog

不要写成：

com.XingYu.User

广泛发布的包通常还会使用：

反向域名

作为名称前缀。

例如某个组织拥有：

example.com

可能使用：

com.example.project

这种形式。

2.34 命名的核心不是“越长越好”

下面这个名字：

int theCurrentAgeOfTheLoggedInUserInThisSystem;

虽然表达得很完整，但过度冗长。

好的名称应该：

在清晰与简洁之间取得平衡。

例如：

int currentUserAge;

已经能够表达足够信息。

三、使用方法

3.1 正确使用三种教学注释

一个完整例子：

/**
 * 演示 Java 中常见的三种注释写法。
 */
public class CommentDemo {

    /**
     * 程序入口。
     *
     * @param args 命令行参数
     */
    public static void main(String[] args) {

        // 当前用户年龄
        int age = 18;

        /*
         * 当前案例只演示注释，
         * 暂时不处理用户输入。
         */
        System.out.println(age);
    }
}

其中：

/**
 */

承担 API 文档说明。

//

承担局部简短说明。

/*
 */

承担普通多行说明。

3.2 给变量起有意义的名字

不推荐：

String a = "LingXi";
int b = 18;
double c = 99.5;

3.3 方法名尽量表达行为

不推荐：

data()

更清楚的可能是：

loadUserData()

或者：

saveUserData()

因为：

data

无法表达方法到底干什么。

3.4 不要重复翻译代码

不推荐：

// 年龄等于 18
int age = 18;

如果没有额外业务含义，这个注释可以直接删除。

更有价值：

// 平台规定 18 岁及以上用户才能申请当前服务
int minimumAge = 18;

3.5 TODO 应该表达真正未完成事项

例如：

// TODO 补充手机号格式校验

它表达的是：

当前实现明确存在一个待完成任务。

不要到处写：

// TODO

却不说明：

做什么；
为什么；
当前缺什么。

四、原理与进阶

4.1 注释在词法分析阶段发生了什么

Java 源文件最初是一串字符。

编译器需要逐步把它们识别为 Java Token。

例如：

int age = 18;

最终会识别出类似：

int
age
=
18
;

这些具有语法意义的 Token。

而注释：

// user age

不会成为普通 Java 语法 Token。

可以把过程简化成：

Java 源文件
     │
     ▼
字符流
     │
     ▼
词法处理
     │
     ├── 空白 → 用于分隔等
     ├── 注释 → 丢弃
     └── Token
          ├── Identifier
          ├── Keyword
          ├── Literal
          ├── Separator
          └── Operator

这解释了为什么：

注释本身不参与普通运行逻辑。

4.2 为什么字符串中的 `//` 不是注释

例如：

String text = "// hello";

其中：

// hello

位于字符串字面量内部。

Java 词法分析知道当前正在处理：

String Literal

因此其中的：

//

不会重新启动一段普通单行注释。

同样：

String text = "/* hello */";

其中：

/*
*/

也只是字符串内容的一部分。

4.3 标识符为什么能够使用中文

Java 源代码以 Unicode 为基础。

Identifier 中的 JavaLetter 并不仅限于：

A-Z
a-z

因此 Java 能够支持大量不同语言文字中的字符成为 Identifier。

但是语言提供能力，不等于团队必须使用。

这再次体现：

语法能力
≠
工程规范

4.4 为什么 `$` 合法但不推荐

$ 在 Java Identifier 中具有历史兼容意义。

很多工具生成代码时可能产生包含 $ 的名称。

例如编译器、框架或者代码生成工具内部可能使用它区分某些生成结构。

因此普通业务开发中主动大量使用：

$user
$order
$count

会降低可读性，并可能与工具生成名称风格混淆。

所以：

合法，但通常不推荐作为普通业务命名习惯。

五、实践应用

5.1 代码审查时先看名字

假设看到：

int d = 30;

第一反应应该是：

30 是什么？

再看：

int retentionDays = 30;

马上知道：

它描述的是保留天数。

好的命名本身就是一种：

自文档化（Self-documenting）

能力。

5.2 修改名字优先使用 IDE Refactor

例如：

int count;

后来发现应该叫：

studentCount;

不要简单在整个项目中：

Ctrl + H

进行盲目文本替换。

IDEA 可以使用：

Rename Refactoring

理解 Java 符号引用关系并完成更安全的重命名。

这也是上一章 IDE 能力在真实开发中的直接应用。

5.3 注释应该记录无法直接从代码看出的业务原因

例如：

// 第三方接口每分钟最多允许请求 100 次
int requestLimitPerMinute = 100;

这里的：

为什么是 100

来自外部业务约束。

代码本身无法告诉后来开发者原因。

因此这类注释非常有价值。

六、常见问题

6.1 Java 到底是两种注释还是三种注释？

两个说法处于不同层面。

语言规范的词法层面：

// ...
/* ... */

两种 Comment。

教学和 Javadoc 使用层面通常区分：

单行注释
多行注释
文档注释

三种常见写法。

6.2 注释越多，代码质量越好吗？

不是。

高质量代码应该尽量：

名称清晰；
结构清楚；
职责明确。

只有代码本身无法充分表达的：

原因；
约束；
特殊规则；
API 使用方法；

再由注释补充。

6.3 为什么多行注释不能嵌套？

因为 Java 词法规则不把：

/* ... /* ... */ ... */

处理成递归嵌套结构。

遇到结束标记以后，传统注释就结束。

6.4 `true`、`false`、`null` 是 Java 关键字吗？

严格按照 JLS：

true
false

是 Boolean Literal。

null

是 Null Literal。

都不是 Keyword。

6.5 `_` 可以作为变量名吗？

单独：

在现代 Java 中已经是保留关键字，不能作为普通变量名。

但是：

_count

属于更长的 Identifier，在相应位置语法上可以合法。

工程中仍然通常推荐：

count

这样的名称。

6.6 `$money` 合法吗？

在 Identifier 语法规则允许的情况下可以合法。

但是：

合法不等于推荐。

普通业务变量更推荐：

money

6.7 中文变量名合法吗？

例如：

int 年龄 = 18;

Java Unicode Identifier 规则可以允许。

但工程上通常仍推荐使用：

int age = 18;

等英文名称。

6.8 为什么命名规范不是 Java 语法？

因为：

int USERAGE = 18;

可能完全合法。

编译器不会因为它没有使用小驼峰而拒绝编译。

命名规范解决的是：

代码可读性与团队一致性。

而不是：

编译器能不能解析。

七、练习与验收

7.1 知识问答

什么是注释？它的主要作用是什么？
Java 教学中常见哪三种注释写法？
为什么 JLS 的词法结构只定义两类 Comment，而教学中通常说三种？
单行注释与多行注释分别适合什么场景？
多行注释能否嵌套？
文档注释与普通多行注释有什么区别？
什么是 Javadoc？
为什么不应该给每一行代码都写注释？
什么叫“解释 Why，而不是翻译 What”？
什么是 Java Keyword？
什么是 Reserved Keyword？
什么是 Contextual Keyword？
true、false、null 分别属于什么？
什么是 Identifier？
为什么数字不能作为普通标识符的第一个字符？
$ 和 _ 能否出现在标识符中？
中文变量名为什么可能合法，但工程中通常不推荐？
类、方法、变量、常量和包通常采用什么命名风格？

7.2 代码阅读

代码一

在不运行程序的情况下阅读：

public class CommentRead01 {

    public static void main(String[] args) {

        int age = 18;

        // age = 20;

        /*
        age = 30;
        */

        System.out.println(age);
    }
}

回答：

最终哪几条赋值语句会真正参与编译？
预测控制台结果。
注释是在 Java 程序运行时才被 JVM 跳过的吗？
请说明你的推理过程。

代码二

public class CommentRead02 {

    public static void main(String[] args) {

        System.out.println("// hello");

        String text = "/* world */";

        System.out.println(text);
    }
}

回答：

字符串中的 // 是否会开启单行注释？
字符串中的 /* */ 是否会开启多行注释？
为什么？

代码三

判断下面哪些名称可能属于合法 Java Identifier，并说明理由：

userName
2name
class
$money
user_name
_count
_
学生姓名
true
null
MAX_VALUE

不要只写“合法 / 非法”，必须解释对应规则。

7.3 手写代码

任务一：CommentDemo

从零创建：

CommentDemo.java

要求同时使用：

类文档注释；
main 方法文档注释；
单行注释；
多行注释。

注释不能全部只是把代码翻译成中文。

任务二：Javadoc

为下面这个方法设计完整文档注释：

public static double calculateBMI(double weight, double height) {
    return weight / (height * height);
}

要求至少说明：

方法用途；
weight 的含义；
weight 的单位；
height 的含义；
height 的单位；
返回值含义。

然后尝试使用：

javadoc

生成文档。

任务三：命名重构

将下面代码中的低质量名称全部重命名：

public class A {

    public static void main(String[] args) {

        String a = "LingXi";
        int b = 18;
        double c = 95.5;

        System.out.println(a);
        System.out.println(b);
        System.out.println(c);
    }
}

要求：

类名有明确含义；
变量名表达业务含义；
使用正确大小写风格。

7.4 Debug

观察：

public class CommentDebug01 {

    public static void main(String[] args) {

        /*
         * 登录业务开始

        System.out.println("login");
    }
}

要求：

先判断问题属于编译期还是运行期。
找到最核心的源码结构问题。
解释编译器为什么无法正确处理后续内容。
最后再修复代码。

7.5 综合训练

设计一个：

StudentProfile

程序。

至少包含：

学生姓名
年龄
Java 成绩
所在城市

要求：

类名符合 Java 命名规范；
变量名符合 Java 命名规范；
至少包含一个高价值单行注释；
至少包含一个类级 Javadoc；
不允许出现大量“翻译代码”的无价值注释；
不使用 a、b、c 表示真实业务数据；
完成后说明哪些名称是 Java 语法要求，哪些只是工程规范。

7.6 本章验收

不查看教程完成下面检查：

[ ] 能手写单行、多行、文档注释。
[ ] 能解释为什么 JLS 与教学资料对“注释种类”的说法看起来不同。
[ ] 能说明 Javadoc 的基本作用。
[ ] 能识别低价值和失效注释。
[ ] 能解释 Reserved Keyword 与 Contextual Keyword 的区别。
[ ] 知道 true、false 和 null 并不是 Java Keyword。
[ ] 能判断常见 Identifier 是否合法。
[ ] 知道单独 _ 在 Java 21 中不能作为普通变量名。
[ ] 能解释中文 Identifier 为什么语法上可能合法。
[ ] 能正确命名包、类、方法、变量和常量。
[ ] 能解释“语法合法”和“工程推荐”之间的区别。

一、学习目标

二、核心知识

2.1 什么是注释

2.2 注释会不会被程序执行

2.3 Java 教学中的三种注释

2.4 单行注释

2.5 多行注释

2.6 多行注释不能嵌套

2.7 文档注释

2.8 为什么规范说“两种注释”，教程却说“三种

2.9 文档注释应该放在哪里

2.10 常见 Javadoc 标签

@param

@return

@throws

@deprecated

2.11 使用 javadoc 生成文档

2.12 注释不是越多越好

2.13 注释应该解释“Why”，而不仅仅是“What”

2.14 失效注释比没有注释更危险

2.15 什么是关键字

2.16 Java 21 中关键字并不只是传统列表

2.17 保留关键字

const 和 goto

strictfp

_

2.18 上下文关键字

2.19 true 和 false 是关键字吗

2.20 null 是关键字吗

2.21 什么是标识符

2.22 标识符可以由什么组成

2.23 数字不能作为标识符开头

2.24 _ 和 $

2.25 中文变量名合法吗

2.26 标识符区分大小写

2.27 合法标识符与好名字是两回事

2.28 什么是命名规范

2.29 类名：UpperCamelCase

2.30 方法名：lowerCamelCase

2.31 变量名：lowerCamelCase

2.32 常量名：UPPER_SNAKE_CASE

2.33 包名通常全部小写

2.34 命名的核心不是“越长越好”

三、使用方法

3.1 正确使用三种教学注释

3.2 给变量起有意义的名字

3.3 方法名尽量表达行为

3.4 不要重复翻译代码

3.5 TODO 应该表达真正未完成事项

四、原理与进阶

4.1 注释在词法分析阶段发生了什么

4.2 为什么字符串中的 // 不是注释

4.3 标识符为什么能够使用中文

4.4 为什么 $ 合法但不推荐

五、实践应用

5.1 代码审查时先看名字

5.2 修改名字优先使用 IDE Refactor

5.3 注释应该记录无法直接从代码看出的业务原因

六、常见问题

6.1 Java 到底是两种注释还是三种注释？

6.2 注释越多，代码质量越好吗？

6.3 为什么多行注释不能嵌套？

6.4 true、false、null 是 Java 关键字吗？

6.5 _ 可以作为变量名吗？

6.6 $money 合法吗？

6.7 中文变量名合法吗？

6.8 为什么命名规范不是 Java 语法？

七、练习与验收

7.1 知识问答

7.2 代码阅读

代码一

代码二

代码三

7.3 手写代码

任务一：CommentDemo

任务二：Javadoc

任务三：命名重构

7.4 Debug

7.5 综合训练

7.6 本章验收

`@param`

`@return`

`@throws`

`@deprecated`

`const` 和 `goto`

`strictfp`

`_`

2.19 `true` 和 `false` 是关键字吗

2.20 `null` 是关键字吗

2.24 `_` 和 `$`

4.2 为什么字符串中的 `//` 不是注释

4.4 为什么 `$` 合法但不推荐

6.4 `true`、`false`、`null` 是 Java 关键字吗？

6.5 `_` 可以作为变量名吗？

6.6 `$money` 合法吗？