naming-thingslisted

# 命名之道 ## 何时用 - 新建变量、函数、类、接口、常量、文件时。 - review 代码发现读了三遍还不明白某个名字是什么意思。 - 重构阶段整理命名一致性,消除同一概念在项目里的多种叫法。 - 发现自己犹豫"这个变量叫 `d` 还是 `data` 还是 `result`"时�� ## 核心规则 ### 1. 名字说"是什么/做什么",不说"怎么做";避免缩写与匈牙利命名 **规则：** 名字应表达业务语义或功能意图,不暴露实现机制;除公认缩写(URL、HTTP、ID)外不缩写,不加类型前缀。 **为什么：** AI 生成的代码里频繁出现 `strName`、`arrItems`、`bIsValid`(匈牙利命名)或 `tmp`、`res`、`d`(无意义缩写)。读者看到 `strName` 不但没获得额外信息(类型系统已知道它是 string),反而被迫在脑中翻译。缩写制造认知负担:是 `mgr` 还是 `manager`?是 `usr` 还是 `user`?项目大了以后每个人缩写规则不同,读起来像乱码。 **怎么做：** - 写出完整单词:`invoiceTotal` 而非 `invTot`,`userRepository` 而非 `usrRepo`。 - 去掉类型前缀:`isActive` 而非 `bIsActive`,`items` 而非 `arrItems`。 - 例外:循环变量 `i/j`、数学公式里的 `x/y` 等约定俗成的短名可保留。 --- ### 2. 布尔用 is/has/can;函数用动词;集合用复数 **规则：** 按照名字的语法角色选前缀/形式:布尔量用 `is`/`has`/`can`/`should`,函数/方法用动词短语,集合类型用复数名词。 **为什么：** AI 生成的代码常出现 `active`(布尔?状态枚举?名词?)、`data()`(函数?属性?做什么?)、`item`(一个?列表?)这类模糊命名。读者必须跳到定义处才知道类型,增加认知跳跃次数。命名的语法结构是免费的文档:看到 `isLoading` 立刻知道是 bool,看到 `fetchUser()` 立刻知道是动作且有 I/O。 **怎么做：** - 布尔:`isLoading`、`hasPermission`、`canEdit`、`shouldRetry`。 - 函数:`getUserById()`、`validateEmail()`、`sendNotification()`。 - 集合:`users`、`orderItems`、`pendingTasks`(复数)。 - 避免:`active`、`flag`、`check()`、`handle()`、`process()`——太泛,说不清做什么。 --- ### 3. 一致性:同一概念全项目同一词,不混用 fetch/get/load **规则：** 确定一个动词/名词后全项目统一使用,相同语义的操作不能在不同文件里用不同词。 **为什么：** AI 在不同上下文里会随意选词:`getUserById` 在一处、`fetchUserById` 在另一处、`loadUser` 在第三处,做的是完全相同的事。读者面对三种叫法会疑惑:有什么区别?哪个有缓存?哪���走网络?实际上三者等价,只是 AI 在不同时刻生成了不同的词。这种不一致积累到一定规模后,代码库变成"方言集合",新人入手极难。 **怎么做：** - 项目初期在 `GLOSSARY.md`