Java编码规范相关-开发⼿册-IDEA插件-P3C-sonarLint-代码格式化 编码规范
按摩鞋垫⼀、⼤⼚的规范⼿册
1、阿⾥巴巴《Java开发⼿册（嵩⼭版）》
⼴为流传的⼿册，我基本每个开发机都会放⼀本，⽤来做参考，想起来就看⼀下，反思⾃⼰之前的瑕疵，完善和修正⾃⼰的编码习惯。
⽽且，阿⾥之前推出了IDEA的P3C扫描插件，可以实时扫描类中的规范问题，作为⼊门和参考是很不错的选择，⽽且⽂档的⽤⾊和排版也很⼯整，看着很舒服。
2、华为《代码规范⽂档》
华为内部使⽤，但是华为对于信息管控很严格，所以对于流出的⼿册资料，时效性不及时。
但是，规范属于“前⼈栽树，后⼈乘凉。“，所以作为参考即可。
⽽且，华为内部开发有很多⾃研和集成的扫描插件，可以检测和扫描很多规范和建议类内容。
离线语音识别方案
3、唯品会《唯品会Java开发⼿册》
github/DarLiner/vjtools
基于阿⾥开发⼿册等，由唯品会在github VJTools开源的⼀本⼿册
简略参考：mp.weixin.qq/s/cdmzMmE9j31P1Bak0PyXTg
4、wiki在线Java编码规范
u.edu/confluence/display/java/SEI+CERT+Oracle+Coding+Standard+for+Java
SEI CERT Oracle Coding Standard for Java
⼀个在Wiki上在线编译的Java规范
⼆、参考书籍
1、《Clean Code》
2、《Effective Java》
三、IDEA插件
1、阿⾥编码规范实时监测⼯具
alibaba-java-coding-guidelines
插件下载即⽤，可以扩展
2、findbugs、checkstyle等
常见的⼏种规范插件
3、sonarLint
1. 最早是简单的checkstyle，后来有同样基于⽂本分析的PMD
2. 再后来⼜有了基于字节码分析的FindBugs
3. 再后来出现了Sonar，集成了三者
4. ⼜后来，Facebook基于Findbugs推出⾃⼰实战派的规则FB-Contrib，再次被Sonar集成
文字拼接
5. 最后，Sonar发展了⾃⼰的语法分析体系，改进并替换了Checkstyle 和 PMD的规则
四、IDEA代码格式化⼯具
1、eclipse code formatter
导⼊阿⾥的P3C代码格式化⼯具，并且⽀持⾃定义
github/alibaba/p3c
唯品会格式化模板
github/vipshop/vjtools
2、JavadDoc
3、JUnitGenerator
⽣成单元测试代码
(⼀) 命名规约
Rule 1. 【强制】避免成员变量，⽅法参数，局部变量重名复写，避免引起混淆 类的私有成员变量名，不与⽗类的成员变量重名
⽅法的参数名/局部变量名，不与类的成员变量重名(getter/setter例外)
下⾯错误的地⽅，在编译时都是合法的，但给阅读者带来极⼤的障碍。
public class A {
int foo;
}
public class B extends A {
int foo;//WRONG
int bar;
public void hello(int bar){//WRONG
int foo =0;//WRONG
}
public void setBar(int bar){//OK
this.bar = bar;
}
}
(⼆) 格式规约
Rule 1. 【强制】使⽤项⽬组统⼀的代码格式模板，基于IDE⾃动的格式化
基于阿⾥P3C插件，也可以安装阿⾥的模板，建议统⼀
10）IDE的默认代码格式模板，能简化绝⼤部分关于格式规范(如空格，括号)的描述。
2）统⼀的模板避免不同开发者之间，因为格式不统⼀，产⽣代码合并冲突。另外，代码变更⽇志中因为格式不同引起的变更，也会掩盖了真正的逻辑变更。
3）设定项⽬组统⼀的⾏宽，建议120。
4）设定项⽬组统⼀的缩进⽅式(Tab或⼆空格，四空格均可)，基于IDE⾃动转换。
Rule 2. 【推荐】通过空⾏进⾏逻辑分段
⼀段代码也是⼀段⽂章，需要合理的分段。
不同组的变量之间，不同业务逻辑的代码⾏之间，插⼊⼀个空⾏，起逻辑分段的作⽤。
⽽联系紧密的变量之间、语句之间，则尽量不要插⼊空⾏。
int width;
int height;
String name;
Rule 3.【推荐】避免IDE格式化
对于⼀些特殊场景（如使⽤⼤量的字符串拼接成⼀段⽂字，或者想把⼤量的枚举值排成⼀列），为了避免IDE⾃动格式化，常常会把注释符号//加在每⼀⾏的末尾，这会导致很多⽆意义的视觉⼲扰。
可以使⽤@formatter:off和@formatter:on来包装这段不需要格式化的代码，让IDE就会跳过这段的格式化。
[外链图⽚转存失败，源站可能有防盗链机制，建议将图⽚保存下来直接上传(img-YNJfoIh9-1624848159255)
(C:\Users\86134\AppData\Roaming\Typora\typora-user-images\image-20210624094409061.png)]
// @formatter:off
...
// @formatter:on
(三) 注释规约
Rule 1.【推荐】基本的注释要求
代码将被⼤量后续维护，注释如果对阅读者有帮助，不要吝啬在注释上花费的时间。
除了特别简单特别清晰的类（见规则2，3），每个类都尽量编写注释，说明类的⽬的和使⽤⽅法。
对外提供的公有⽅法，同样需要清晰的描述，期待的输⼊，对应的输出，错误的处理和返回码，尽量把可能的异常都⼀⼀列明。
Rule 2. 【推荐】通过更清晰的代码来避免注释
在编写注释前，考虑是否可以通过更好的命名，更清晰的代码结构，更好的函数和变量的抽取，让代码不⾔⾃明，此时不需要额外的注释。
Rule 3. 【推荐】删除空注释，⽆意义注释
《Clean Code》建议，如果没有想说的，不要留着IDE⾃动⽣成的，空的@param，@return，@throws 标记，让代码更简洁。
反例：⽅法名为put，加上两个有意义的变量名elephant和fridge，已经说明了这是在⼲什么，不需要任何额外的注释。
/**
* put elephant into fridge.
*
* @param elephant
* @param fridge
* @return
*/
public void put(Elephant elephant, Fridge fridge);
Rule 4.【推荐】避免创建⼈，创建⽇期，及更新⽇志的注释
代码后续还会有多⼈多次维护，让我们相信源码版本控制系统能做得更好。
Rule 5. 【强制】代码修改的同时，注释也要进⾏相应的修改。尤其是参数、返回值、异常、核⼼逻辑等的修改
Rule 6. 【强制】类、类成员变量、类⽅法的注释必须使⽤Javadoc规范，使⽤/**xxx*/格式，不得使⽤//xxx⽅式
正确的JavaDoc格式可以⽤在很多地⽅，⽐如在IDE中，查看调⽤⽅法时，不进⼊⽅法即可悬浮提⽰⽅法、参数、返回值的意义，提⾼阅读效率。
Rule 7. 【推荐】JavaDoc中不要为了HTML格式化⽽⼤量使⽤HTML标签和转义字符
如果为了HTML版JavaDoc的显⽰，⼤量使⽤<p\><pre\>这样的html标签，以及<" 这样的html转义字符，对严重影响直接阅读代码时的直观性，⽽直接阅读代码的⼏率其实⽐看Html版JavaDoc⼤得多。
有时候Java Doc的格式化也要求<p>之类的标签来换⾏，可以配置让IDE不进⾏Java Doc的⾃动格式化。
Rule 8. 【推荐】TODO标记，清晰说明代办事项和处理⼈
清晰描述待修改的事项，保证过⼏个⽉后仍然能够清楚要做什么修改。
如果近期会处理的事项，写明处理⼈。
通过标记扫描，经常清理此类标记，线上故障经常来源于这些标记但未处理的代码。
正例：
//TODO:calvin use xxx to replace yyy.
反例：
//TODO: refactor it
Rule 9. 【推荐】合理处理注释掉的代码
如果后续会恢复此段代码，在⽬标代码上⽅⽤///注释详细说明，⽽不是简单的注释掉。
如果⽆⽤，则直接删除（版本管理⼯具保存了历史代码）。
(四) ⽅法设计
Rule 1. 【推荐】⽅法的长度度量
⽅法尽量不要超过100⾏，或其他团队共同商定的⾏数。华为是50，但是对于⼤⼀些的业务和注解较多的情况，感觉80较为合理
另外，⽅法长度超过8000个字节码时，将不会被JIT编译成⼆进制码。
，默认值改为100
Facebook-Contrib:Performance - This method is too long to be compiled by the JIT
Rule 2. 【推荐】⽅法的语句在同⼀个抽象层级上
反例：⼀个⽅法⾥，前20⾏代码在进⾏很复杂的基本价格计算，然后调⽤⼀个折扣计算函数，再调⽤⼀个赠品计算函数。
此时可将前20⾏也封装成⼀个价格计算函数，使整个⽅法在同⼀抽象层级上。
Rule 3. 【推荐】为了帮助阅读及⽅法内联，将⼩概率发⽣的异常处理及其他极⼩概率进⼊的代码路径，封装成独⽴的⽅法
if(seldomHappenCase){
hanldMethod();
}
try{
...
}catch(SeldomHappenException e){
handleException();
}
Rule 4. 【推荐】尽量减少重复的代码，抽取⽅法
超过5⾏以上重复的代码，都可以考虑抽取公⽤的⽅法。
Rule 5. 【推荐】⽅法参数最好不超过3个，最多不超过7个
1）如果多个参数同属于⼀个对象，直接传递对象。
例外: 你不希望依赖整个对象，传播了类之间的依赖性。
2）将多个参数合并为⼀个新创建的逻辑对象。
例外: 多个参数之间毫⽆逻辑关联。
3）将函数拆分成多个函数，让每个函数所需的参数减少。
Rule 6.【推荐】下列情形，需要进⾏参数校验
1） 调⽤频次低的⽅法。网篮法
2） 执⾏时间开销很⼤的⽅法。此情形中，参数校验时间⼏乎可以忽略不计，但如果因为参数错误导致中间执⾏回退，或者错误，代价更⼤。
3） 需要极⾼稳定性和可⽤性的⽅法。
4） 对外提供的开放接⼝，不管是RPC/HTTP/公共类库的API接⼝。
如果使⽤Apache Validate 或 Guava Precondition进⾏校验，并附加错误提⽰信息时，注意不要每次校验都做⼀次字符串拼接。
//WRONG
Validate.isTrue(length >2,"length is "+keys.length+", less than 2", length);
汽水取样//RIGHT
Validate.isTrue(length >2,"length is %d, less than 2", length);
Rule 7.【推荐】下列情形，不需要进⾏参数校验
1） 极有可能被循环调⽤的⽅法。
人脸识别怎么建模2） 底层调⽤频度⽐较⾼的⽅法。毕竟是像纯净⽔过滤的最后⼀道，参数错误不太可能到底层才会暴露问题。
⽐如，⼀般DAO层与Service层都在同⼀个应⽤中，所以DAO层的参数校验，可以省略。
3） 被声明成private，或其他只会被⾃⼰代码所调⽤的⽅法，如果能够确定在调⽤⽅已经做过检查，或者肯定不会有问题则可省略。
即使忽略检查，也尽量在⽅法说明⾥注明参数的要求，⽐如vjkit中的@NotNull，@Nullable标识。
Rule 8.【推荐】禁⽤assert做参数校验
豫公网安备41160202000603
站长QQ:729038198
关于我们
投诉建议