1. 命名这件事为什么值得单独花时间说先抛一个问题你上一次被一段别人的代码折磨到想摔键盘是什么时候我猜大概率不是算法看不懂而是变量名看不懂。String a xxx; int b 1;这种代码逻辑再简单也让人不敢碰因为你根本不知道a和b是干嘛用的。反过来一段命名清晰的代码哪怕逻辑复杂一点读起来也像在看一篇结构分明的文章哪里是入口、哪里是出口一目了然。Java 里的变量命名规范尤其是小驼峰写法camelCase就是解决这个问题的第一道关卡。它不是考试知识点也不是面试八股文而是每个写 Java 的人从第一天起就应该内化成习惯的东西。很多人觉得名字嘛能看懂就行但能看懂和一眼就懂之间的差距在真实项目里会被放大得非常恐怖。一个类可能有几十个字段一个方法里可能有十几二十个局部变量如果每个人都按自己的习惯随便起名这个项目三个月后就会变成一座谁都不想进去的屎山。我做过几次代码评审最深的体会就是命名规范不是一个锦上添花的选项而是雪中送炭的必需品。它直接影响代码的可读性、可维护性甚至影响团队协作的效率。你想想一个新人接手项目先看的是什么不是注释不是文档而是变量名和方法名。变量名起得好他大概率能顺着逻辑往下走变量名起得烂他连从哪儿开始问问题都不知道。所以这篇我打算把 Java 变量命名这件事从规则到实操彻底捋一遍重点就在小驼峰写法上同时也把常量、类名、包名这些和变量命名强相关的边界一并说清楚。适合谁看刚学 Java 的初学者写了两三年代码但命名习惯比较随意的人以及在团队里负责代码评审、想推动规范落地的人。看完之后你会发现命名规范真不是啥高深理论它就是一套可以立刻上手的实操规则。2. 小驼峰写法的拼写规则从单词边界到缩写词的处理2.1 小驼峰的核心规则首单词小写后续单词大写小驼峰写法的定义很多人背得出来第一个单词首字母小写后面每个单词的首字母大写其余字母全部小写单词之间不添加空格、下划线或连接符。举例userName、totalPrice、maxRetryCount。这个规则本身不复杂但真正写代码的时候边界情况多得让人头大。先说最简单的场景。单单词变量名全部小写即可name、count、status、flag。两个及以上的单词按规则拼接orderId订单ID、createTime创建时间、currentSeconds当前秒数。核心逻辑就是首词小写后续词首字母大写但切分单词这件事比看起来难。举个例子getUserID和getUserId你们团队写哪个这两者背后是对缩写词的处理分歧。我见过不少项目里变量名写成userID、orderNO、httpURL的说实话看着就浑身难受。这里我给出一个比较主流的约定缩写词在变量名里一律按普通单词处理。也就是说ID写成IdURL写成UrlHTTP写成Http。所以变量名是userId、orderNo、httpUrl而不是userID、orderNO、httpURL。为什么这么约定核心原因是可读性和视觉一致性。如果某个变量叫userIID或者httpURLConnection全大写字母堆在一起扫一眼根本分不清单词边界在哪里。而httpUrl、userId这种写法单词之间的边界很清楚读起来很顺。当然也有一部分团队坚持userID这种写法认为它保留了缩写的原始形式。我不评判对错但我会强调一点团队内一定要统一最怕的就是一个项目里既有人写userId又有人写userID那代码风格的割裂感会非常重。2.2 两个字母和三个字母单词的处理细节还有一类容易忽略的情况只有两个字母的单词。比如id本身就是两个字母所以单独出现时写id作为变量的一部分时比如orderId第二个字母要不要大写按照首单词小写后续单词首字母大写的规则Id的d不应该大写因为规则只要求首字母大写。但很多人会写成orderID这是把整个缩写都大写了。这里有个业界比较接受的折中方案两个字母的缩写词在变量名中保持首字母大写、第二个字母小写比如Id、No所以orderId、serialNo是推荐写法而URL、XML这类三个字母以上的缩写同样按普通单词处理写成Url、Xml。多说一句如果变量名以缩写词开头比如想表达URL地址按小驼峰规则应该是urlAddress而不是URLAddress因为首词要小写。这个规则很多人一开始不适应写多了就顺了。你去看主流 Java 源码比如 Spring 框架里的url、http相关字段基本都是这个风格这其实就是行业里用脚投票的结果。2.3 为什么变量名里不建议出现下划线Java 语法层面变量名里用下划线是合法的除了 Java 9 之后单独一个下划线_被禁用但命名规范层面标准的 Java 变量命名是不用下划线的。原因很实在user_name和userName摆在一起你读哪个快显然是后者。下划线在视觉上会切断单词而小驼峰通过大小写起伏形成边界读起来更顺滑。另外Java 里的下划线不是没有用武之地它被明确留给常量命名了。常量使用全大写加下划线比如MAX_CONNECT_COUNT、DEFAULT_TIMEOUT这是 Java 社区几十年沉淀下来的约定。如果你把普通变量也写成user_Name这种混搭风格读者很难判断这到底是个常量还是变量。所以规则很简单局部变量、成员变量、参数名用驼峰常量用全大写加下划线两者不要混。3. 变量命名的边界场景布尔值、集合、常量与临时变量3.1 布尔类型变量用动词短语代替模糊的单词布尔变量是最能体现命名功力的地方。很多人喜欢写boolean flag true;或者boolean status false;看到这种代码我真的是血压飙升。flag是什么旗status是啥状态你是在表达启动状态还是完成状态语义完全不明。布尔变量的最佳实践是用is、has、can、should这类助动词开头直接问一个问题让变量的值就是问题的答案。举个例子判断用户是否激活命名isActive判断用户是否有权限命名hasPermission判断系统能否重试命名canRetry。这样写的好处是读代码的时候你不需要额外思考这个变量的含义——看到if (isActive)你直接就知道了这是在判断是否激活逻辑顺序和自然语言完全一致。有几个细节值得注意。第一is开头在 JavaBean 规范里有特殊含义对于boolean类型的属性它的 getter 方法名是isXxx而不是getXxx所以如果属性叫activeIDE 生成的 getter 就是isActive这只影响方法名不影响字段名。第二如果属性是包装类型Booleanis开头的字段生成的 getter 也可能是isEmpty这种形式和boolean的行为有细微差异这里不做展开但你们团队最好在代码规范里明确一下。第三别把is和has用混。is表达是不是某种状态has表达有没有某个东西比如isActive是不是激活的、hasChildren有没有子节点语义有分工别混着用。3.2 集合类变量优先用复数而不是把类型塞进名字集合变量的命名很多人会写成ListString userList new ArrayList();或者MapString, Object dataMap new HashMap();。这种命名不能说错但算不上好。核心问题是List和Map是类型名不是业务语义把类型编码进变量名里信息量很低。更好的做法是直接用复数或者用能体现集合语义的单词。比如ListUser users一眼就能看出这是一个用户集合MapString, Integer scoreMap你不一定非得去掉Map但如果能改成scoresByStudentId这种形式语义会更精确。我自己在代码里比较常见的习惯是List 类型直接复数Map 类型用值By键或者加上Map后缀来区分比如userById、configMap。这样在同一个方法里出现users和user时单复数的区分天然就传达了一个是集合、一个是单个元素的信息非常自然。还有一点关于数组的命名。比如String[] names和String[] nameArray我更推荐前者因为数组本身就是一组值用复数命名就够了Array后缀同样是类型编码。3.3 常量与枚举全大写还是驼峰把常量归入变量命名一起讨论是因为太多人在常量这块拿不准。Java 里真正的常量是指static final修饰的字段规范命名是全大写加下划线MAX_VALUE、DEFAULT_PORT、RETRY_TIMES。这个规则从 Java 诞生起就没变过也没什么争议。但有个容易混淆的点常量池里如果存储的是对象引用比如private static final Logger LOGGER ...很多人会觉得这不是基本类型也该用小驼峰吧。实际上主流的做法仍然是全大写或者至少保持团队统一。而枚举类型本身是特殊的类枚举值的命名在 Java 里通常是全大写但如果你见过一些较新的风格偏好大驼峰比如enum Color { Red, Green }也不少见。这里我不展开争议只提一个建议如果你在一个既有项目里先看项目里别的枚举怎么写的跟着已有风格走永远比发明新风格安全。3.4 临时变量与循环变量短命变量不代表可以随便起名有人说临时变量嘛反正生命周期短叫temp无所谓。这话大错特错。临时变量短命但阅读它的人未必短命——你写完这段代码一个月后回来看String temp parseJson(data);这个temp到底是解析出来的 JSON 字符串还是错误信息谁知道呢。我的建议是临时变量可以短但不能无意义。temp、data、info、obj这类名字基本没有任何信息量尽量别用。循环里的i、j、k作为索引是长期以来形成的惯例属于可接受范畴但要遵守一个约束嵌套不要超过三层三层以上就该用有意义的变量名了。而在 for-each 循环里千万不要再用i这种索引名直接写业务含义比如for (User user : users)这个user就非常棒。4. 我在代码评审中最常看到的五种命名坏味道4.1 类型后缀String nameString 和 int countInt第一种坏味道是把数据类型塞进变量名。String userString getUser();、int ageInt getAge();这种写法我在代码评审里隔三差五就能看到。为什么不好因为 Java 是静态类型语言变量的类型编译器已经清楚地告诉你了你在名字里再写一遍String、Int属于重复信息。更严重的是如果哪天这个变量的类型从String变成了StringBuilder你还得把变量名也改一遍不改的话名字就是在说谎。有用例可以简单说明一下如果你的变量名本身能体现业务语义比如userName不会有人觉得它是个整数但如果你非写成userNameString不仅名字变长了信息量一点没增加。例外情况是有时候为了区分两个语义相同但来源不同的值可以在名字里加个限定词比如userNameFromDb和userNameFromInput这比userNameDb、userNameInput可读性高也比userName1、userName2强得多。4.2 拼音命名zongjine、fuwuqi 这类中式英语第二种坏味道是拼音命名。String fuwuqi server;、int zongjine 100;这种变量名在中小型团队里出现频率不低。拼音命名的最大问题是你不是在做中文编程代码是要给所有懂英文的开发者看的。如果团队里来了一个只会英文的同事他看fuwuqi会一头雾水看server就秒懂。有人说我英语不好怕写错这个担忧其实不需要。变量名用的都是高频词汇你只要会查词典或者用 IDE 的补全功能就能写对。退一步说哪怕英语语法不完美写成serverAddr也比fuwuqi强。如果你是团队负责人我很建议维护一份命名术语表把项目里常用的业务词的中英文对照写清楚比如订单order、用户user、余额balance这样所有人都能照着用逐渐就把拼音从代码里挤出去了。4.3 同一个概念多种叫法order、trade、purchase 各写各的第三种坏味道是同一个业务概念在代码里有好几种命名而且每种还都有人用。比如订单这个概念有人写成order有人写成trade有人写成purchase三个人写的三个变量名指的全是同一件事。这种命名混乱的危害比拼音大得多它会让代码搜索失效。你想找所有订单相关的逻辑得搜order、trade、purchase三遍还担心漏掉某个变体。这种问题没有技术上的解法纯粹靠团队约定。我的做法是在项目启动阶段就拉一份领域词汇表把所有核心业务概念的标准英文翻译定下来评审代码时拿着这张表逐字对。不要小看这一步它省下来的时间绝对比投入的多。4.4 缩写过度usr、cfg、msg 这种暗语第四种坏味道是缩写过度。usr是什么user对吧cfg是什么config。msg是什么message。这些缩写看起来省了几个字母实际上给读者增加了记忆负担每看到一个缩写脑子里都要进行一次破译。而且破译不总是一次成功的——msg到底是message还是mastercnt是count还是center上下文不同含义完全可能不一样。有一个很简单的判断标准如果一个缩写在团队里不能做到人人秒懂就不要用。id、no、err这种高频缩写算例外其他尽量写全。现代 IDE 都有自动补全写完整单词并不比写缩写多花多少时间省下的那点键盘成本远小于读者多花的理解成本。4.5 无意义的数字后缀a1、a2、param1、param2第五种坏味道是数字后缀命名。String a1 张三; int a2 20;或者String param1 request.getParam(name); String param2 request.getParam(age);。这种命名的问题在于a1和a2之间是什么关系为什么1和2要区分命名里完全看不出来。如果两个变量的区别只是来源不同或者顺序不同那你应该把这个区别说出来比如firstName和lastName或者minValue和maxValue。还有一种常见情况是重构遗留问题某个变量最初只有一个result后来需要两个结果就改成了result1和result2。这种递增式命名是代码腐烂的重要原因看到这种情况你应该停下来想想这两个result真的需要同时存在吗如果必须存在它们各自的业务含义是什么想清楚了命名自然就有了。5. 把命名规范变成团队习惯的落地工具与流程5.1 在编译阶段就卡住集成 Checkstyle 的实践光靠口头强调命名规范效果约等于零。人的记忆会疲劳压力大的时候很容易回到命名随意的老路。真正有效的方法是把规范做成自动化检查在编译阶段就拦住不规范的命名。Java 生态里最常用的工具就是 Checkstyle它通过配置文件定义命名规则比如变量名必须匹配某个正则表达式不符合就报编译警告或错误。下面是一段我常用的规则配置可以约束局部变量、参数名和成员变量module nameMemberName property nameformat value^[a-z][a-zA-Z0-9]*$/ message keyname.invalidPattern value成员变量命名必须使用小驼峰写法且不能以下划线开头/ /module module nameLocalVariableName property nameformat value^[a-z][a-zA-Z0-9]*$/ message keyname.invalidPattern value局部变量命名必须使用小驼峰写法且不能以下划线开头/ /module module nameParameterName property nameformat value^[a-z][a-zA-Z0-9]*$/ message keyname.invalidPattern value方法参数命名必须使用小驼峰写法且不能以下划线开头/ /module module nameConstantName property nameformat value^[A-Z][A-Z0-9]*(_[A-Z0-9])*$/ message keyname.invalidPattern value常量命名必须使用全大写加下划线格式/ /module注意看正则^[a-z][a-zA-Z0-9]*$它强制要求首字母必须是小写字母后面可以跟大小写字母和数字。这样userName能通过user_name和UserName都会被拦住。把这几条规则放进团队的checkstyle.xml配上 Maven 或 Gradle 插件每次构建时自动检查基本就能把命名不守规矩的问题消灭在萌芽状态。有个配置小技巧报错级别建议先用warning不要一上来就error。因为有些历史代码可能旧命名很多直接设 error 会让构建挂掉团队成员怨声载道。先 warning 跑几周等大家适应了、存量代码清理得差不多了再升级成 error这样推进阻力小很多。5.2 用 IDE 模板和快捷键养成肌肉记忆自动化检查解决的是事后拦截还有一个事前预防的手段利用 IDE 的模板和代码补全让好的命名更容易写出来差的命名更不容易出现。IntelliJ IDEA 里有个叫 Live Templates 的功能你可以提前定义好常用循环、判断、集合遍历的模板让 IDE 自动生成带良好命名的骨架代码。比如 for-each 遍历默认模板就是for (User user : users) { }只要你在敲for之后按 TabIDEA 就会自动帮你补全User user : users并且自动推导出单数形式的变量名user这比你每次手打一行for再纠结变量名快得多。类似的还有sout输出、psvm主方法等模板本质上都是把注意力从怎么拼写里解放出来让人专注于语义命名。针对集合类型还有一个很实用的小技巧当你需要给集合变量命名时直接在声明里用复数比如ListString names new ArrayList();IDE 补全的时候通常会自动根据元素类型提示一个合适的复数名。把这种习惯养成肌肉记忆之后你基本不需要刻意思考这个集合叫什么优秀候选名会自己蹦出来。5.3 代码评审清单把命名检查固化为流程的一环代码评审是命名规范的最后一站也是很多团队执行力最弱的环节。评审的时候大家盯着逻辑、性能、安全性这些大问题命名这种小问题很容易被一带而过。但我觉得命名问题恰恰是评审里最值得单独拿出来看的维度因为它直接决定了下一个人接手这段代码时的体验。我的做法是在团队代码评审的检查清单里专门加一栏命名检查包含几个固定问题这个变量名能不能被看的人三秒钟内理解命名里有没有出现类型后缀、拼音或过度缩写单复数使用是否一致有没有同一个概念多个叫法如果一个变量名在评审中被指出修改成本通常很低但收益是长期且确定性的。顺便分享一个很有效的实操技巧评审一段代码时试着不看方法体只看方法名、参数名和局部变量名先猜这段代码是干嘛的。如果你猜得八九不离十说明命名是合格的如果你完全猜不出来说明命名有问题需要改。这个方法我用过很多次虽然在复杂的业务逻辑里预测准确率会下降但往往会准确暴露那些起名起得特别离谱的变量效果非常直观。5.4 历史代码整改从增量规范到存量清理最后聊聊存量代码的问题。很多团队不是不想规范命名是项目太老历史代码里到处都是temp、data、a1之类的命名一提整改就觉得工程量太大改坏怎么办。我的经验是分三步走。第一步先守增量从今天起新提交的代码必须符合命名规范用 Checkstyle 强制卡住不允许新的坏味道混入第二步找热点不要想着把所有老代码一次改完而是优先清理那些经常被修改、被阅读的模块比如核心实体类、公共工具类、高频调用的业务类这些地方命名清晰了对日常开发效率的改善最大第三步随缘清理在修 bug 或者做小需求的时候顺手把碰到的、明显不规范的变量名改掉积少成多。这中间有个安全前提别在重构命名的时候夹带逻辑变更。改名字就是改名字行为不应该有任何变化否则出了 bug 你分不清是改名改错了还是逻辑本来就错了。有条件的话可以在改名后跑一遍单元测试和集成测试用结果兜底。回头说说我在实际项目里的体会。命名规范这件事单看每一条规则都很小、很简单甚至有点不起眼。但把它们叠加起来对代码可读性的提升是肉眼可见的。我自己经历过从随便写名到严格自查的过程最明显的变化不是代码好看了而是回头翻自己三个月前写的代码时不需要再靠回忆苦撑了——变量名本身就是最好的注释。如果你刚接触 Java或者正在为团队的代码风格头疼我真心建议从今天起每写一个变量名之前花两秒钟想一下这个名字去掉注释之后别人能看懂它想表达什么吗小驼峰只是表面形式真正值钱的是你愿意为下一个人多花的那点心思。