【代码规范】Java程序员的编程笔记（培养好习惯）

【辰兮要努力】：hello你好我是辰兮，很高兴你能来阅读，昵称是希望自己能不断精进，向着优秀程序员前行！

博客来源于项目以及编程中遇到的问题总结，偶尔会有读书分享，我会陆续更新Java前端、后台、数据库、项目案例等相关知识点总结，感谢你的阅读和关注，希望我的博客能帮助到更多的人，分享获取新知，大家一起进步!

吾等采石之人，应怀大教堂之心，愿大家奔赴在各自的热爱里…

一、注释清晰

每个类、方法都写清楚注释 且行注释应该在代码之前另起一行

备注如下是Java方法里面的注释模板

   /**
     * 功能描述: 
     *
     * @param 方法参数的说明
     * @return 对方法返回值的说明
     * @author 模块的作者
     * @date 编写日期
     */

普通实体类的注解

/**
 * @author: 辰兮要努力
 * @createDate: 2021-8-8 11:56:10
 * @description: Java编程反思
 */

注释可以很好的帮助后续要维护，拓展你代码的人阅读

【强制】类、类属性、类方法的注释必须使用Javadoc规范，使用/*内容/格式，不得使用//xxx方式。

说明：在IDE编辑窗口中，Javadoc方式会提示相关注释，生成Javadoc可以正确输出相应注释；在IDE中，工程调用方法时，不进入方法即可悬浮提示方法、参数、返回值的意义，提高阅读效率。

更多详细的学习可以参考阿里巴巴java开发手册详解-编程规约 -注释规约

二、命名规范

开发前期一定要培养自己的好习惯，要思考如何让代码写好

具体包括方法，类名以及变量名等

最常见的基础方法如下，命名中不要出现中英文拼接或者中文拼音的情况，可以百度一下对应的英文翻译，命名要正规

Service/DAO层方法命名规约
1) 获取单个对象的方法用get做前缀。
2) 获取多个对象的方法用list做前缀。
3) 获取统计值的方法用count做前缀。
4) 插入的方法用save(推荐)或insert做前缀。
5) 删除的方法用remove(推荐)或delete做前缀。
6) 修改的方法用update做前缀

领域模型命名规约
1) 数据对象:xxxDO，xxx即为数据表名。
2) 数据传输对象:xxxDTO，xxx为业务领域相关的名称。
3) 展示对象:xxxVO，xxx一般为网页名称。
4) POJO是DO/DTO/BO/VO的统称，禁止命名成xxxPOJO

举几个简单的案例

【强制】 代码中的命名均不能以下划线或美元符号开始，也不能以下划线或美元符号结束

反例: name / __name / $Object / name / name$ / Object$

【强制】 代码中的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式。

反例: DaZhePromotion [打折] / getPingfenByName() [评分] / int 某变量 = 3

正例: alibaba / taobao / youku / hangzhou 等国际通用的名称，可视同英文。

【强制】类名使用 UpperCamelCase 风格，必须遵从驼峰形式，但以下情形例外:(领域模型 的相关命名)DO / BO / DTO / VO等。

正例:MarcoPolo / UserDO / XmlService / TcpUdpDeal / TaPromotion

反例:macroPolo / UserDo / XMLService / TCPUDPDeal / TAPromotion

【强制】方法名、参数名、成员变量、局部变量都统一使用 lowerCamelCase 风格，必须遵从驼峰形式。

正例: localValue / getHttpMessage() / inputUserId

【参考】枚举类名建议带上 Enum 后缀，枚举成员名称需要全大写，单词间用下划线隔开。

说明: 枚举其实就是特殊的常量类，且构造方法被默认强制是私有。

正例: 枚举名字:DealStatusEnum，成员名称: SUCCESS / UNKOWN_REASON。

备注：枚举全部大写即可，在项目中要巧用枚举

枚举学习参考：一篇文章彻底读懂Java枚举Enum类（案例详解）

三、入参校验

入参校验，普通的常量和集合的判空

在Java的Service层的实现类中，一定要有完善的入参校验

部分公司DAO层也是自己封装的框架，所以单独拿出来也要有自己的入参校验

普通字符串的入参校验

StringUtils.isEmpty(String str) 判断某字符串是否为空，为空的标准是 str==null 或 str.length()==0

StringUtils.isBlank(String str) 判断某字符串是否为空或长度为0或由空白符(whitespace) 构成

System.out.println(StringUtils.isEmpty("   "));       //false

System.out.println(StringUtils.isBlank("   "));       //true

集合的入参校验

判断list集合不能为空

CollectionUtils.isEmpty(list)

如下的判断方法也可以，不过我更建议使用如上集合帮助类，简介清晰

if(null == list || list.size() ==0 ){
 
　　//为空的情况
　　 
}else{
 
　　//不为空的情况
 
}

在service层的第一步就应该是入参校验，如果传入参数有问题，直接返回对应的错误提示，这样也可以提高接口的响应速度

四、日志清晰

有效的输出日志，比如抛出异常，打印有效的参数更好的帮助我们解决异常的问题

日志的案例：使用参数化形式{}占位，[]进行参数隔离

 logger.debug("Processing trade with param1:[{}] and param2: [{}] ", param1, param2); 

不推荐使用

logger.debug("Processing trade with param1: " + param1 + " param2: " + param2);

异常添加对应的日志外,部分逻辑比较复杂的接口，我们需要详细的了解具体走到哪里出问题了，入参等是否进入都可以添加对应的日志，方便我们阅读

常见错误总结

1、不要抛出异常后又输出日志，不然会造成重复输出日志。

try {
    // ...
} catch (Exception e) {
    // 错误案例 
    LOG.error("xxx", e);
    throw new RuntimeException();
}

2、不要使用错了日志的级别

try {
    // ...
} catch (Exception e) {
    // 错误案例- 如果捕获异常就写error
    LOG.info("XX 发生异常...", e);
}

正常打印日志记录入参，出参就用info，错误日志就用error

五、返参清晰

及时的输出返回值，同时msg里面的信息要准确和清晰

    /** 状态码 */
    public static final String CODE_TAG = "code";

    /** 返回内容 */
    public static final String MSG_TAG = "msg";

    /** 数据对象 */
    public static final String DATA_TAG = "data";

比如传入的人员ID不能为空; 比如未配置文件存储服务器等;

如上的清晰描述可以让前后端在联调或者线上出现操作问题的时候更好的排查问题

很多时候不要直接返回一个服务端错误，能写清楚就写清楚

六、常量提取

常量类：常量等要提取出来，创建常量类、避免魔法值的使用

阿里强制规定不允许任何魔法值（未经定义的常量）直接出现在代码中

---

提取的好处分享

当我们常量提取后：如定义了一个公共的试题类型编号COMMON

当我们后台再做逻辑操作的时候，只要引用这一个同样的常量即可

    /**
     * 公共的试题类型编号
     */
    public static final String TYPE = "COMMON";

此时后面所有service层逻辑中引用都可以直接使用这一个定义的常量，如果此时因为某种特殊原因我将公共的试题类型编号修改为“COMMON_CODE”,这样也只需要在此处一个地方修改即可；

如上的操作提高了的代码的拓展性和复用性； 不然我要全局搜索哪里用到了公共试题这个编号，然后一个个修改;

七、方法复用

帮助类：可以统一复用的方法要写在帮助类中，统一的复用；

如日期的帮助类,获取IP的帮助类，文件上传的公共类等等…

能统一抽出来复用的类就统一抽出来

Java逻辑层中同样抽离公共方法复用

同样Java中service层的逻辑代码里面两个业务封装逻辑相同的方法能复用的地方就抽离出来

如查询热门帖子和查询最新帖子-逻辑层中封装的点赞，关注，用户状态等的业务逻辑一样，唯一不一样的是底层查询出来一个根据权重查询，一个根据时间查询;

这样我们把封装的方法抽离出来，做成共用的，这样提高了代码的复用性

八、代码美化

代码美化 去掉空白： Ctrl + Shift + J

       格式化代码： Ctrl + Alt + L
       一致的缩进

九、巧用工具

巧妙地使用工具检查代码

idea里面下载工具，搜索框中输入alibaba 选择 Alibaba Java Coding Guidelines，点击 右边的Install按钮进行安装，安装完成之后重启idea

  <font face="楷体" size=4>找到要扫描的包或者类点击右键

效果如下：【强制】类、类属性、类方法的注释必须使用Javadoc规范，使用/*内容/格式，不得使用//xxx方式

当然还有很多其它的代码检测工具，合理使用即可

十、提交规范

提交代码Git或者SVN描述 要清晰; 方便清晰地知道代码提交代码或者修改的内容

feat - 新功能 feature
fix - 修复 bug
docs - 文档注释
style - 代码格式(不影响代码运行的变动)
refactor - 重构、优化(既不增加新功能，也不是修复bug)
perf - 性能优化
test - 增加测试
chore - 构建过程或辅助工具的变动
revert - 回退
build - 打包

参考案例

[feat]-影院管理模块- 功能描述: 新增影院模块首页查询功能

[fix]-影院管理模块- 功能描述: 解决影院模块首页根据区域查询失败的问题

当然上述提交的格式还可以更加的规范，在开发过程跟着项目的提交规范走即可，培养好的习惯，方便阅读代码的人，也方便后续排查问题

当我们书写代码的时候就要思考如何把代码写好，而不仅仅是完成！

上述总结还有很多待完善的地方，仅供参考，后续会不断的反思和完善自己的思维！争取成为一个合格的开发工程师！

期待有更多的进步！

---

非常感谢你阅读到这里，如果这篇文章对你有帮助，希望能留下你的点赞👍 关注❤️ 分享👥 留言💬thanks！！！

2021年8月29日22:13:35 愿你们奔赴在自己的热爱里！