本文目录导读：
以下是从命名规范和命名逻辑两个维度，梳理出的具体审查关注点、常见问题及改进建议。
审查命名规范
这部分关注的是命名是否符合团队或社区的既定风格,确保一致性。
| 审查维度 | 关注点 | 好的示例 | 坏的示例 / 问题 | 审查建议 |
|---|---|---|---|---|
| 大小写规则 | 类/接口/枚举（大驼峰）、方法/变量（小驼峰）、常量（全大写+下划线）、包名（全小写） | class UserService void getUserInfo() MAX_RETRY_COUNT |
class user_service (类) void GetUserInfo() (方法) max_retry_count (常量) |
检查是否严格遵循语言规范，不一致会破坏阅读节奏。 |
| 缩写与简写 | 优先使用全称，除非是公认的缩写。 | userId (ID) htmlContent (HTML) |
usrId (不清晰) XML_CTX (令人困惑) |
禁止随意创造缩写或简写，除非团队有明确、共享的缩写表。 |
| 术语一致性 | 同一概念在整个项目中命名统一。 | 统一使用 fetchUser， updateUser |
有时用 queryUser, 有时用 getUser (混淆) |
尤其关注DAO层、Service层、Controller层的命名风格是否一致。 |
| 拼写检查 | 单词拼写正确，无常见错误。 | configuration |
configuraton (少字母) / config (与全称不一致) |
IDE拼写检查插件（如Code Spell Checker）是必备的。 |
| 前缀/后缀规范 | 接口/抽象基类、集合类型、状态/Tag | UserService (接口) / UserServiceImpl (实现) userList / userIdSet |
实现类叫 UserIService (语法错误) userData (模糊，是list还是map?) |
集合变量最好指明类型（List, Map, Set），接口和实现类命名要清晰区分。 |
审查命名逻辑
这部分比规范更重要，它评估命名是否准确、清晰地反映了所代表实体的职责、行为、或角色。
| 审查维度 | 关注点 | 好的示例 | 坏的示例 / 问题 | 审查建议 |
|---|---|---|---|---|
| 意图清晰 | 名词、动词选择恰当，直接反映功能。 | sendEmail(), calculateTotalPrice(), isValidUser() |
doProcessing(), handleEvent(), checkThatCustomer() (过于泛化) |
每个命名都应该能回答“它是什么？”或“它能做什么？”。 |
| 避免误导 | 命名不应暗示错误类型或不符合实际行为。 | userManager (如果只管理创建/删除) |
userManager (如果它还负责发送邮件、生成报告——职责不单一) |
名称应精确匹配其所做的事情，如果职责超出名称暗示，应拆分或重命名。 |
| 长度适当 | 作用域越小，名字可越短；作用域越大，名字需越长越精确。 | 循环变量: i, j 公共API: findActiveUsersByRoleAndDept() |
tmp, data, obj (无处不在，无法理解) findActiveUsersThatAreInTheAdminRoleAndFromTheSalesDept (过长的、描述性的命名) |
平衡，好的命名是“自解释”的，但不要冗长到影响可读性。 |
| 动词时态/条件 | 函数名暗示其副作用或返回值类型。 | isDeleted() (返回布尔) setActive(boolean) (有副作用) |
deleteUser() (如果它实际只是标记删除而不是物理删除) |
布尔方法通常以 is, has, can, should 开头，带副作用的命令式方法名。 |
| 与业务对齐 | 使用业务领域的通用术语。 | 在电商系统中用 Order, Cart, Invoice |
TransactionRecord1 (与业务无关) 处理前数据 (中文混合, 不专业) |
强烈建议与产品经理、业务分析师沟通，确保命名符合领域语言。 |
审查流程中的具体操作
-
准备阶段 (PR提交者)
- 自检清单： 在提交代码前，花几分钟对照上述审查点过一遍自己的命名,这能减少审查者的工作量。
- 注释辅助： 如果某个命名在特定上下文下有特殊含义，可以加一行简短注释说明（但不应该依赖注释来解释命名，命名首先应具备自解释性）。
-
审查阶段 (Reviewer)
- 快速扫描： 第一遍快速浏览PR，重点关注类和公开方法名,看看是否一眼就能理解模块的职责。
- 精确质疑： 当看到一个模糊的命名（如
data,result,obj），果断提出：“这个对象作用域很大，data无法体现其业务含义，能否改为userRegistrationData或paymentResult？” - 结合上下文： 审查命名时，不能孤立地看，要放在它所在的类、模块、甚至整个项目中来考虑。
- 区分硬性规定与软性建议：
- 硬性规定（必须改）： 拼写错误、违反团队命名规范（如大驼峰写成下划线）、命名严重误导。
- 软性建议（可以讨论）： 命名不完美但可接受、长度略有争议、与另一个类似的命名风格略有不同，对于这类，可以提出更优建议，但不要强制要求,避免过度优化。
常见命名逻辑问题举例
- 错误的使用“Manager”或“Utils”类： 如果一个类叫
UserManager，却涵盖了创建、删除、发送邮件、生成报表、读写缓存等所有用户相关操作，说明职责不清，应拆分成UserService,EmailService,UserReportGenerator,UserCacheService等。 - 布尔变量/方法名歧义：
isNotApproved(双否定) vsisApproved(简洁清晰)。getDeletedUsers()是返回已删除用户列表，还是返回“是否被删除”的布尔值？应改为fetchDeletedUsers()或isDeleted()。 - 过度使用“magic number”或无意义的变量名：
int i = 1000; // 毫秒，表示超时时间应改为int TIMEOUT_MS = 1000;,使用可读的常量替代魔法数字。 - 忽略生命周期的命名：
tempUserList,customerDetailsArr这些名字暗示了它们是临时变量或数组，但实际可能是持久化的某部分，应反映其稳定角色，如pendingUsers,orderItemList。
建议用于代码审查工具（如GitLab/GitHub）的评论模板
当你发现不好的命名时，可以用以下结构化方式进行评论，既指出了问题,也提供了改进方向：
评审意见： 问题点： 变量名 / 方法名
[具体名字]不够清晰 / 具有误导性。 原因分析： 看到这个名字，我会误解为[误导的理解]，但实际上它代表的是[实际的含义]。 改进建议： 建议重命名为[更合适的名字]，因为它更直接地表达了[某个目的/属性/行为]。 示例/参考： 例如在同类场景中，我们使用了[类似的好名字]来保持一致性。
在代码审查中，命名审查不是吹毛求疵，而是预防认知错误和沟通成本的关键一环，一个团队若能始终坚持“准确、一致、自解释”的命名原则，代码库的可维护性会大大提升，审查时，先检查“是否符合规范”（一致性），再深入思考“是否准确反映逻辑”（清晰度与正确性），最后考虑“是否与业务领域对齐”（业务相关性）。
