简介华为JAVA编码规范面向Java初学者、团队协作开发者及需要统一代码风格的工程团队帮助解决命名随意、缩进混乱、注释缺失与异常处理不规范等常见问题。内容覆盖程序块四空格缩进、大括号分界符对齐、长语句换行、命名规则、空行与空格对齐以及类与接口注释、成员变量和公有方法注释、package.html包说明、文件头注释等要求并强调源程序有效注释量需在30%以上对方法内部throw与throws声明的非RuntimeException也要求在注释中标明。资源共1个PDF文件压缩包约90KB类型单一、轻量便于离线查阅或打印适合作为个人自查清单与团队规范培训底稿。已有982人浏览学习读者可据此逐条对照现有工程沉淀可复用的注释模板、命名约定和异常说明习惯进而提升代码可读性、可维护性与多人协作效率。1. 一份被当成“八股答案库”的编码规范其实该怎么用很多人第一次接触华为 JAVA 编码规范是在准备笔试面试的时候——把里面的条目当选择题背背完就忘。但真正在团队里推过规范的人会发现这份文档解决的不是“考试选什么”而是代码评审为什么总在吵同一件事缩进用几个空格、注释写在哪、异常到底该谁捕获。它给出的是一条条可判定的规则而不是“保持代码优雅”这类没法落地的口号。它适合三类人刚从培训班出来、代码能跑但结构散的新人接手别人遗留工程、需要快速统一风格的维护者以及准备做静态检查、想把规范写成 Checkstyle 规则的技术负责人。全文从缩进、命名、注释、异常、并发一路排到复杂度上限本质是一份“可自动化校验”的清单。下面按可执行的方式拆重点讲规则背后的判断依据、对应的检查配置以及推行时最容易翻车的地方。2. 缩进、换行与括号把格式规则写成可校验的约束2.1 4 空格缩进与禁用 TAB 的真实原因规范第 1 条和第 7 条是格式里最容易被忽略的一对缩进用 4 个空格且对齐只用空格键、不用 TAB。单看像洁癖实际原因在协作——TAB 在不同编辑器里渲染宽度不同一个人设 4、一个人设 8同一份代码在两台机器上就是两种布局Git diff 里看不出任何差异评审时却吵得不可开交。空格是绝对值TAB 是相对值跨编辑器一致性只能靠绝对值保证。常见做法是在 IDE 里打开“用空格代替 TAB”并顺手统一换行符。以 VS Code 为例在.vscode/settings.json里固化下来{ editor.insertSpaces: true, editor.tabSize: 4, editor.detectIndentation: false, files.eol: \n, files.trimTrailingWhitespace: true }insertSpaces保证按 Tab 键插入的是空格detectIndentation必须关掉否则打开别人用 TAB 的文件时编辑器会自动跟随规范就白设了。files.eol统一成\n避免 Windows 的 CRLF 混进仓库导致全文件 diff。提示detectIndentation是推行规范失败率最高的一项团队里只要有一个人漏关他的提交就会把整份文件重排。2.2 大括号同行还是换行、长表达式怎么断规范第 2 条要求{和}各占一行、在同一列并与引用语句左对齐这其实是 Java 圈里经典的“Allman 风格”和 Sun 官方推荐的 KR 同行风格相反。两者没有绝对优劣选它的理由是块边界在垂直方向上一目了然嵌套多的时候比同行括号更容易数清层级。争议点在 switch、匿名内部类和 lambda 上Allman 会让代码行数明显变长。第 3 条讲长表达式换行规则很具体超过 80 字符就断行断点选在低优先级操作符处且操作符放在行首。判断依据是——把、||放在行首读者扫左边缘就能立刻知道这是“多条件的第几段”如果放行尾视线要跑到每行末尾才找得到连接关系。if (fileName ! null new File(logPath fileName).length() logConfig.getFileSize() retryCount MAX_RETRY) { writeFileThread.interrupt(); }全部对齐在缩进后的同一列条件之间的平行关系一眼可读。第二行的相对if再缩进一层是因为它属于条件表达式内部不是新语句。2.3 用 Checkstyle 把这些条目变成 CI 卡点规则写了没人执行等于没写常见做法是引入 Checkstyle把格式条目翻译成可自动跑检查的配置module nameChecker module nameLineLength property namemax value80/ /module module nameFileTabCharacter/ module nameTreeWalker module nameNeedBraces/ module nameLeftCurly property nameoption valuenl/ /module module nameRightCurly property nameoption valuealone/ /module module nameOperatorWrap property nameoption valueNL/ /module /module /module检查项对应规范条目关键参数触发后的实际含义FileTabCharacter第 7 条无文件内出现 TAB需替换为空格LineLength第 3 条max80超过 80 字符需换行LeftCurly第 2 条optionnl左大括号必须另起一行RightCurly第 2 条optionalone右大括号独占一行NeedBraces第 5 条无if/for/while 即使单句也必须有花括号OperatorWrap第 3 条optionNL换行处的操作符必须在行首LeftCurly的nl表示 new lineeol才是同行OperatorWrap的NL同理是整份规范里最能体现“Allman 倾向”的两个配置项。接入 Maven 时绑定到validate阶段本地mvn validate和流水线跑的是同一套规则避免“本地过、CI 挂”。2.4 空格使用的边界判断第 8 条最容易理解偏对等操作符、、前后加空格非对等且关系密切的立即操作符.、[]索引、i后面不加空格。核心判据是“空格服务于可读性不是机械加”。括号内侧不加空格、多重括号之间不加空格且连续空格不得超过一个——这条是针对用空格做表格对齐这种反模式的那种写法一旦有人改了字段名整段对齐全崩。3. 命名规则与类结构组织从包名倒置到成员摆放顺序3.1 包名域后缀倒置与命名层次规范第 37 条要求包名用域后缀倒置加自定义包名全部小写格式为com.huawei.产品名.模块名或com.huawei.部门名.项目名。倒置是为了让同一组织的包在文件系统里天然聚集也避免和顶级域名冲突。示例里的com.huawei.iin.websmap、com.huawei.insa2.msgtrans体现的是两种粒度产品线按“产品模块”铺部门内部按“部门项目”铺。命名对象首字母规则单词间规则示例包名全小写点分隔全小写com.huawei.iin.websmap类/接口大写驼峰OrderInformation方法小写驼峰calculateRate属性小写驼峰customerName常量全大写下划线分隔MAX_VALUE存取方法小写get/set/is前缀getTypeisFinishedsetVisible第 45 条是个务实妥协函数名超过 15 个字母可用去元音或行业缩写getCustomerInformation缩成getCustomerInfo。这条之所以必要是因为 Java 没有类型别名长方法名在调用链里会迅速撑爆 80 字符行长限制和前面的换行规则直接打架。3.2 类成员不交叉摆放与存取范围收敛第 9 条要求类属性和方法不要交叉放置不同存取范围的成员也不要交叉固定顺序是公有属性 → 保护属性 → 私有属性 → 公有方法 → 保护方法 → 私有方法。这条的价值在大型类里才显现——按访问级别分区后类的对外接口集中在上半部分一眼看清这个类暴露了什么私有实现沉在下面。第 46 条进一步收口不是必须public的用protected不是必须protected的用private。判断依据是“最小可见性”可见范围越小改动时波及面越可控。这条在重构时特别有用把误开的public收成private往往能立刻暴露出哪些地方在跨类直连内部状态。第 115 条更狠——类中不要使用非私有的非静态属性。这等于强制属性全部走 getter/setter代价是代码变长收益是字段变更时只需改一处且能拦截非法赋值。3.3 toString、equals 与 hashCode 的成对约束规范里有几条关于对象基本方法的硬约束所有数据类必须重载toString()返回有意义内容第 51 条重载equals()必须同时重载hashCode()第 122 条实现equals()时先用getClass()或instanceof做类型比较再比字段第 107 条。Override public boolean equals(Object obj) { // 1. 先做类型比较类型不符直接返回 if (this obj) { return true; } if (obj null || getClass() ! obj.getClass()) { return false; } OrderInformation other (OrderInformation) obj; return Objects.equals(orderNo, other.orderNo); } Override public int hashCode() { return Objects.hash(orderNo); }getClass() ! obj.getClass()保证了子类和父类实例不会误判相等比裸用instanceof更严格hashCode必须用同一组参与equals的字段否则对象放进HashMap会出现“能 put 进去却 get 不出来”的经典问题。这两条必须成对单改一个就是往集合里埋雷。4. 注释体系与异常处理30% 有效注释怎么落地4.1 package.html、文件头与方法级 JavaDoc规范把注释拆成四个层级包注释、文件注释、类/接口注释、成员与方法注释且要求有效注释量在 30% 以上。包注释不写在代码里而是放一个package.html到包路径下内容是 HTMLhtml body p一句话描述本包作用/p p详细描述本包内容/p p产品模块名称br公司版本信息/p /body /html用package.html而不是包内文件注释是因为 JavaDoc 工具有专门约定生成文档时会把这个文件挂到包级别页面上。文件注释放在文件头部、包声明之前字段包括文件名、版权、描述、修改人、修改时间、修改内容、跟踪单号类与方法注释放在package之后、class之前方法注释必须含param、return、exception。/** * 计算订单的实际费率。 * * param order 订单对象不能为 null * return 计算后的费率单位为万分之几 * throws IllegalStateException 订单状态不合法时抛出 */ public int calculateRate(Order order) { // ... }第 34 条有个容易被忽略的细节JavaDoc 提取简介时只取第一句话所以方法描述第一句必须是一句话概括并以句号结尾详细描述另起一段否则生成的文档首页会是一大段文字。4.2 30% 注释率怎么算、怎么不写成废话注释率 有效注释行 / 总行数空注释、被注释掉的死代码不算有效注释。真正让这条不落空的是第 29、30 条通过好的命名让代码自注释注释只补充“为什么”不复述“是什么”。规范给的反例是//如果 receiveFlag 为真配if (receiveFlag)正例是//如果从连接收到信息——差别在于后者提供了接收来源这一额外信息。第 35 条还要求顺序流程用 1、2、3、4 编号注释在各步骤前比如闰年判断那三段把算法分支的意图直接摊开。注意不要为了凑 30% 而灌水。静态检查公司里通常用 SonarQube 的comment_lines_density指标监控但真正该卡的是一行注释是否提供了代码本身没有的信息。4.3 try-catch-finally 与资源关闭第 52、102 条反复强调数据库操作、IO 操作这类需要close()的对象必须在try-catch-finally的finally里关闭且close()自身要再包一层 try-catch。OutputStream out null; try { out new FileOutputStream(logFile); out.write(content.getBytes(StandardCharsets.UTF_8)); } catch (IOException ioe) { LOGGER.error(写入日志失败: ioe.toString(), ioe); } finally { if (out ! null) { try { out.close(); } catch (IOException e) { LOGGER.error(关闭流失败, e); } } }finally里的close()必须再套 try否则关闭失败会覆盖掉主流程的异常信息。第 53 条要求异常捕获后要么记录日志要么ex.printStackTrace()第 62 条特别指出记录异常不要只存getMessage()要存toString()——因为NullPointerException的 message 常常为空只存 message 的日志等于什么都没留。4.4 异常类型选择与细分捕获规范条目要求反面例子为什么第 55 条运行期异常继承RuntimeException不加throws给参数校验异常加throws调用方被迫处理不该处理的异常第 64 条不要直接catch(Exception)细分处理catch(Exception ex){}吞掉所有异常无法区分处理第 63 条一个方法不抛太多类型异常一个方法throws五种异常调用方 catch 链条过长第 111 条不定义Error和RuntimeException子类自定义Error子类这两类语义已被 JVM 占用第 215 条声明违例用具体子类而非Exceptionthrows Exception调用方被迫宽泛捕获第 49 条处理接口参数校验的归属问题默认由调用者负责避免调用者和被调用者重复校验造成冗余。这条实际推行时需要在接口文档里明确写死否则两边都做或都不做的情况一定出现。5. 复杂度上限与并发细节规范里最硬的那几条5.1 规模指标怎么配成可检查的阈值规范后半段给了一组量化上限这些是整份文档里最容易做自动化卡点的部分指标上限检查手段继承层次5 层Checkstyle/PMD 自定义规则类行数1000 行FileLength类属性数10 个自定义规则类方法数20 个MethodCount方法参数5 个ParameterNumber方法行数30 行MethodLength单方法 return1 个ReturnCount单方法分支语句10 个CyclomaticComplexityMethodLength设 30 行、CyclomaticComplexity设 10这两条组合起来会强制把大方法拆小效果明显但落地阻力也最大——遗留代码一次性全挂。常见做法是先设成告警级别跑一周拿到存量数据的分布再分批设卡而不是第一天就把流水线全红。5.2 循环、集合与字符串的性能约束第 137、140、241 条都指向同一件事集合和StringBuffer创建时初始化容量。原因是ArrayList、HashMap、StringBuffer扩容都要拷贝底层数组默认容量 16 在数据量大时会触发多次 rehash 或数组复制。// 预估元素数量避免扩容时的数组复制 ListOrder orders new ArrayList(orderCount); // 预估最终字符串长度减少底层数组扩容 StringBuilder sb new StringBuilder(orderCount * 32); for (Order order : orders) { sb.append(order.getOrderNo()).append(,); }第 138、235 条进一步要求在循环体内避免调用同步方法、避免 try-catch 块、避免定义变量。循环体是热点任何在循环内创建的临时对象都会成倍放大 GC 压力。第 88 条要求数组复制用System.arraycopy()而不是循环因为前者是本地实现循环版本在 JIT 优化不足时慢一个数量级。5.3 并发写法wait/notify 与同步块并发部分是规范里最值得逐条对照的一段。第 95 条要求线程同步中在循环里做条件测试即用while(isWait) wait()代替if(isWait) wait()。原因是wait()存在虚假唤醒用if判断只检查一次唤醒后条件可能已不成立直接继续执行就是错的。synchronized (lock) { while (!ready) { lock.wait(); // 循环判断防虚假唤醒 } // 条件满足后再执行 }配套的几条第 146 条要求用notifyAll()代替notify()因为notify()只唤醒一个线程被唤醒的未必是条件满足的那个多消费者场景下会丢唤醒第 148 条规定非同步方法里不能调wait()/notify()否则拿不到监视器锁直接抛IllegalMonitorStateException第 247 条禁止使用静态集合因为它生命周期和类一致只增不减是内存泄漏的高发地第 96 条禁用Thread的resume()、suspend()、stop()这三个方法会挂起或中断线程而不释放锁极易死锁。第三类是关于锁粒度的取舍。第 149、253 条建议用同步块代替同步方法第 254 条又要求把所有公有方法定义为同步方法——这两条看着矛盾实际是分场景单例服务类可以用同步块缩小临界区而需要保证整方法原子的工具类才整体加锁。落地的判断标准是临界区里是否有耗时操作有就拆成同步块。5.4 推行时最常见的三类翻车第一类是格式规则和存量代码冲突直接开卡点导致全仓库红正确顺序是先告警后卡点。第二类是注释率的数字游戏为了达标在每行都加注释反而降低可读性应该用“注释是否提供额外信息”人工抽检。第三类是复杂度阈值设得太紧方法 30 行对初学者偏严可以先设 50 行随重构进度逐步收紧。提示规范里第 8、43、59 条这类“写法偏好”条目如int[] index而非int index[]优先级低于可自动化的硬规则推行时不要一视同仁否则团队会因小事消耗掉对规范的信任。6. 把规范封装成模板与规则包的工程化技巧规范真正落地不会停在“读过”而是变成新人拉代码就看到的默认模板。一个低成本的做法是把类注释、方法注释、文件头做成 IDE 的 Live Template。以 IntelliJ IDEA 为例在Settings → Editor → Live Templates里新建一个缩写jdoc模板内容填/** * $DESC$。 * * param $PARAM$ $PARAM_DESC$ * return $RETURN_DESC$ * throws $EXCEPTION$ $EXCEPTION_DESC$ */用$VAR$定义可编辑变量展开时按 Tab 逐项填空。同理给文件头做模板把文件名、版权、修改历史这些固定字段预先写死新建类时自动带出。这一步的价值在于把“记得写注释”从人的自觉变成编辑器行为注释率不用催也能上去。第二招是把 Checkstyle 规则打成团队共享 jar上传到内部仓库各项目pom.xml只引坐标规则升级时全团队一次生效而不是每个项目抄一份 xml 然后各自漂移。配置里建议把LineLength、FileTabCharacter、NeedBraces三条设为error其余设为warning这样 CI 只拦最硬的格式问题风格类问题留给评审讨论。第三招是给自己留个自查脚本在提交前本地跑一遍比等 CI 反馈快得多# 本地先跑一遍格式检查避免推到远端才发现 mvn checkstyle:check -Dcheckstyle.config.locationconfig/checkstyle.xml # 统计注释密度快速看是否低于 30% find src -name *.java | xargs wc -lcheckstyle:check不加-Dcheckstyle.skip时会以非零退出码结束直接阻断提交钩子里的后续步骤后半段的行数统计配合评论行统计工具能粗略估出注释密度用来判断某个包是不是重灾区。真正常用的技巧是先把规则拆成“阻断项”和“观察项”两张表阻断项只留格式和花括号这类零歧义的观察项每周跑一次报表看趋势——规范能活下来靠的从来不是条目够多而是执行成本足够低。本文还有配套的精品资源点击获取