阿里开发手册 嵩山版-编程规约 之代码格式

历史版本

前言

《Java 开发手册》是阿里巴巴集团技术团队的集体智慧结晶和经验总结，经历了多次大规模一线实战的检验及不断完善，公开到业界后，众多社区开发者踊跃参与，共同打磨完善，系统化地整理成册，当前的版本是嵩山版。现代软件行业的高速发展对开发者的综合素质要求越来越高，因为不仅是编程知识点，其它维度的知识点也会影响到软件的最终交付质量。比如：五花八门的错误码人为地增加排查问题的难度；数据库的表结构和索引设计缺陷带来的系统架构缺陷或性能风险；工程结构混乱导致后续项目维护艰难；没有鉴权的漏洞代码易被黑客攻击等等。所以本手册以 Java 开发者为中心视角，划分为编程规约、异常日志、单元测试、安全规约、MySQL 数据库、工程结构、设计规约七个维度，再根据内容特征，细分成若干二级子目录。

另外，依据约束力强弱及故障敏感性，规约依次分为【强制】、【推荐】、【参考】三大类。在延伸信息中，“说明”对规约做了适当扩展和解释；“正例”提倡什么样的编码和实现方式；“反例”说明需要提防的雷区，以及真实的错误案例。

手册的愿景是码出高效，码出质量。现代软件架构的复杂性需要协同开发完成，如何高效地协 同呢？无规矩不成方圆，无规范难以协同，比如，制订交通法规表面上是要限制行车权，实际上是保障公众的人身安全，试想如果没有限速，没有红绿灯，谁还敢上路行驶？对软件来说，适当的规范和标准绝不是消灭代码内容的创造性、优雅性，而是限制过度个性化，以一种普遍认可的统一方式一起做事，提升协作效率，降低沟通成本。代码的字里行间流淌的是软件系统的血液，质量的提升是尽可能少踩坑，杜绝踩重复的坑，切实提升系统稳定性，码出质量。

我们已经在 2017 杭州云栖大会上发布了配套的 Java 开发规约 IDE 插件，下载量达到 162 万人次，阿里云效也集成了代码规约扫描引擎。次年，发布 36 万字的配套详解图书《码出高效》，本书秉持“图胜于表，表胜于言”的理念，深入浅出地将计算机基础、面向对象思想、JVM 探源、数据结构与集合、并发与多线程、单元测试等知识客观、立体地呈现出来。紧扣学以致用、学以精进的目标，结合阿里巴巴实践经验和故障案例，与底层源码解析融会贯通，娓娓道来。《码出高效》和《Java开发手册》稿费所得收入均捐赠公益事情，希望用技术情怀帮助更多的人。

一、编程规约

(三) 代码格式

1. 【强制】如果是大括号内为空，则简洁地写成{}即可，大括号中间无需换行和空格；如果是非空代码块则：

1） 左大括号{?前不换行。

2） 左大括号{?

后换行。

3） 右大括号

}前换行。

4） 右大括号}else后还有 else 等代码则不换行；

}表示终止的右大括号后必须换行。

2. 【强制】左小括号(和右边相邻字符之间不出现空格；右小括号)和左边相邻字符之间也不出现空格；而左大括号前?{需要加空格。详见第 5 条下方正例提示。

反例：if (空格 a == b 空格)

3. 【强制】if/for/while/switch/do 等保留字与括号之间都必须加空格。

4. 【强制】任何二目、三目运算符的左右两边都需要加一个空格。

说明：包括赋值运算符?=?、逻辑运算符?&&?、+-*/符号?等。

5. 【强制】采用 4 个空格缩进，禁止使用 Tab 字符。

说明：如果使用 Tab 缩进，必须设置 1 个 Tab 为 4 个空格。IDEA 设置 Tab 为 4 个空格时，请勿勾选 Use?tab character；而在 Eclipse 中，必须勾选 insert spaces for tabs。

正例： （涉及 1-5 点）

public static void main(String[] args) {
     // 5.缩进 4 个空格
     String say = "hello";
     // 4.运算符的左右必须有一个空格
     int flag = 0;
     // 3.关键词 if 与括号之间必须有一个空格，括号内的 f 与左括号，0 与右括号不需要空格
     if (flag == 0) {
         System.out.println(say);
     }
     // 2.左大括号前加空格且不换行；左大括号后换行
     if (flag == 1) {
         System.out.println("world");
     // 1.右大括号前换行，右大括号后有 else，不用换行
     } else {
     System.out.println("ok");
     // 1.在右大括号后直接结束，则必须换行
     } 
}

6. 【强制】注释的双斜线//与注释内容之间有且仅有一个空格。

正例：?// 这是示例注释，请注意在双斜线之后有一个空格

String commentString = new String();

7. 【强制】在进行类型强制转换时，右括号与强制转换值之间不需要任何空格隔开。

正例：

double first = 3.2d;
int second = (int)first + 2; 

8. 【强制】单行字符数限制不超过 120 个，超出需要换行，换行时遵循如下原则：

1）第二行相对第一行缩进 4 个空格，从第三行开始，不再继续缩进，参考示例。

2）运算符与下文一起换行。

3）方法调用的点符号

.toString()与下文一起换行。

4）方法调用中的多个参数需要换行时，在逗号后进行。

5）在括号(?前不要换行，见反例。

正例：

StringBuilder sb = new StringBuilder();
// 超过 120 个字符的情况下，换行缩进 4 个空格，并且方法前的点号一起换行
sb.append("yang").append("hao")...
     .append("chen")...
     .append("chen")...
     .append("chen");

反例：

StringBuilder sb = new StringBuilder();
// 超过 120 个字符的情况下，不要在括号前换行
sb.append("you").append("are")...append
     ("lucky");
// 参数很多的方法调用可能超过 120 个字符，逗号后才是换行处
    method(args1, args2, args3, ...
    , argsX);

9. 【强制】方法参数在定义和传入时，多个参数逗号后面必须加空格。

正例：下例中实参的 args1，后边必须要有一个空格。

method(args1, ?args2, ?args3);

10.【强制】IDE 的 text file encoding 设置为 UTF-8; IDE 中文件的换行符使用 Unix 格式，不要使用 Windows 格式。

11.【推荐】单个方法的总行数不超过 80 行。

说明：除注释之外的方法签名、左右大括号{}、方法内代码、空行?\n、回车及任何不可见字符的总行数不超过80 行。

正例：代码逻辑分清红花和绿叶，个性和共性，绿叶逻辑单独出来成为额外方法，使主干代码更加清晰；共性逻辑抽取成为共性方法，便于复用和维护。

12.【推荐】没有必要增加若干空格来使变量的赋值等号与上一行对应位置的等号对齐。

正例：

    int one = 1;
    long two = 2L;
    float three = 3F;
    StringBuilder sb = new StringBuilder();

说明：增加 sb 这个变量，如果需要对齐，则给 one、two、three 都要增加几个空格，在变量比较多的情况下，是非常累赘的事情。

13.【推荐】不同逻辑、不同语义、不同业务的代码之间插入一个空行分隔开来以提升可读性。

说明：任何情形，没有必要插入多个空行进行隔开。

非常感谢您阅读到这里，创作不易！如果这篇文章对您有帮助，希望能留下您的点赞👍 关注💖 收藏 💕评论💬感谢支持！！！

听说 三连能够给人 带来好运！更有可能年入百w，进入大厂，上岸

[ 本文作者 ]   软工菜鸡
[ 博客链接 ]   https://blog.csdn.net/m0_67184231
[ 版权声明 ]   如果您在非 CSDN 网站内看到这一行，
说明该死的侵权网络爬虫可能在本人还没有完整发布的时候就抓走了我的文章，
可能导致内容不完整，请去上述的原文链接查看原文。