Java代码规范的重要性

叁歲伎倆 2024-03-16 19:45 76阅读 0赞

#### 目录 ####

*  1 为什么需要代码规范
 *   *  1.1 不规范的案例
     *   *  1.1.1 就因为忘记加个分号，整个程序都崩溃了
         *  1.1.2 我为什么没写注释？
         *  1.1.3 谁动了我的代码？
         *  1.1.4 半小时写的代码，花两个小时调试
     *  1.2 代码编写
     *  1.3 在项目架构
     *  1.4 数据库设计
     *  1.5 编写文档
 *  2 需要代码规范的原因
 *  3 代码规范的重要性
 *   *  3.1 代码规范的好处
     *   *  3.1.1 规范的代码可以促进团队合作
         *  3.1.2 规范的代码可以减少bug处理
         *  3.1.3 规范的代码可以降低维护成本
         *  3.1.4 规范的代码有助于代码审查
         *  3.1.5 规范代码有助于养成代码规范的习惯
 *  4 如何规范代码
 *   *  4.1 阿里巴巴代码规范
     *  4.2 代码规范工具
     *   *  4.2.1 阿里规范插件
         *  4.2.2 sonar
         *  4.2.3 两个工具对比
 *  5 日志打印规范
 *   *  5.1 为什么需要日志
     *  5.2 日志有什么用
     *  5.3 日志框架选择
     *   *  5.3.1 常用的日志框架
         *   *  5.3.1.1 Logging
             *  5.3.1.2 commons-logging
             *  5.3.1.3 Slf4j
             *  5.03.1.4 Log4j
             *  5.3.1.5 Log4j2
             *  5.3.1.6 Logback
         *  5.3.2 日志框架怎么选
         *  5.3.3 记录日志的时机
         *   *  5.3.3.1 编程语言提示异常
             *  5.3.3.2 业务流程预期不符
             *  5.3.3.3 系统核心角色，组件关键动作
             *  5.3.3.4 系统初始化
     *  5.4 日志打印
     *   *  5.4.1 日志变量定义
         *  5.4.2 参数占位格式
         *  5.4.3 日志的基本格式
         *   *  5.4.3.1 日志时间
             *  5.4.3.2 日志级别
         *  5.4.4 日志文件

--------------------

## 1 为什么需要代码规范 ##

![在这里插入图片描述][7b8171988bab481ab10c76ca03ac8f3a.png]

> 可能有同学觉得代码需要突出个人的特点，需要特异化，但是这样就会造成别人阅读起来很困难

代码不仅仅是交给机器来执行的，同时代码也是让其他同事来阅读的，如果代码不规范就会出现各种各样的问题，写多了代码只是觉得代码规范化是一件很自然的事，代码写多了，自然代码规范化咯，地球人都会。

其实不然，我们是不是缺少了小时候，十万个为什么的那种精神，为什么要这样做？为什么要那样做？那么我们为什么要做代码规范化？

### 1.1 不规范的案例 ###

> 下面程序员在修复 bug 时可能会说的一些话或者想法 ，你占了几条？赶紧一起来看看。

![在这里插入图片描述][84b0bf621aea4b02b807dbe010936397.png]

#### 1.1.1 就因为忘记加个分号，整个程序都崩溃了 ####

如果你忘记添加结束分号，只是一个无心的错误，但解析器不理解这一点，它会无情地抛出一个致命错误。然后，你必须再花 20 分钟来查看代码，最后你发现缺少了一个分号，也许这就是调试的“乐趣”。

#### 1.1.2 我为什么没写注释？ ####

> 但对于复杂一些的脚本和程序，就需要某种类型的注释，以便你在几个月后甚至几年后回过头来查看。

有时候你会忘记给函数及其参数、输出格式和其他基本数据添加注释，当出现错误时，你需要调试整个脚本才能找到解决方案时，这无疑会给你添乱，这个时候你就会想，如果当初加一些有用的注释就好了

#### 1.1.3 谁动了我的代码？ ####

> 听起来就像是一种妄想症，但有时你不得不怀疑，正当你忙着补觉时，是谁在写了这些代码

过去几周或几个月忙的项目让你感到沮丧，有时候你会不记得自己往代码库里添加过东西——甚至是上周刚刚查看过的项目！

#### 1.1.4 半小时写的代码，花两个小时调试 ####

> 你一股脑儿写了一个函数，然后函数输出了一个致命的错误

为了找到问题所在，你不得不把其他代码删掉，只留下出问题的那几行代码，当你最终找到问题并把它修复，你会感到筋疲力尽，但同时也松了一口气。

### 1.2 代码编写 ###

> 美观，排着整整齐齐的一行一行，看着就舒服；

要是不使用代码编写规范，每个方法的实现写一遍，相同的函数也不合并，在做重复的事情就是浪费时间的一件事情，而且在修改上也照成一定的困难，所以对于变量、类、接口、事件等都要有一定的规范；

如果是团队开发的话，没有规范更为混乱，要不就你有你的方法，我有我的接口，一个人来一套，那就真的乱套了，写有好味道的代码，我相信是每一个程序员的乐趣。

### 1.3 在项目架构 ###

条理清晰，对于整个的项目，我们也需要一定的规范，项目多了，是采用三层、四层还是n层架构，对于开发的分工、项目的扩展性有很大的帮助，并且使用各种的设计模式，使得代码设计更加合理。

### 1.4 数据库设计 ###

表以及视图的命名需要规范，不要将业务写进存储过程或者函数里面，我们应该都遇到过，一个SQL几千行的代码，修改阅读起来非常的痛苦。

### 1.5 编写文档 ###

编写文档，比较相当枯燥一点，但是对于整个开发的指引也相对重要，要整个团队都要看明白你写的东西，当然也是需要规范化的，如果文档编写的符合规范并且清晰明了，对于后面交接或者问题问题排查都是大有好处的。

## 2 需要代码规范的原因 ##

> 编码规范对程序员非常重要的若干原因

*  软件的80%时间都是处于维护
 *  几乎没有那个软件的维护是由原编写者进行的
 *  编码规范可以改善软件的可读性，使工程师理解新的代码更快速，更彻底。
 *  源代码开源出来后不至于像垃圾一样被人嫌弃

## 3 代码规范的重要性 ##

> 几乎每个项目，每家公司都会定义自己的编码规范，但在真正实施时，却在有意或无意地违背编码规范

程序员不喜欢改变自己的编程习惯，加之，管理者对质量控制不足，导致编码规范往往形同虚设。

有些人会认为：遵守编码规范不能给项目带来利益，也不能让客户看到我们为此付出的努力，其完全是团队自发的行为，没有必要做硬性的要求。

还有些人有更好的理由：编码规范会破坏创造性和程序质量

### 3.1 代码规范的好处 ###

> 编码规范，在软件构件以及项目管理中，甚至是个人成长方面，都发挥着重要的作用，好的编码规范是提高我们代码质量的最有效的工具之一

#### 3.1.1 规范的代码可以促进团队合作 ####

> 一个项目大多都是由一个团队来完成，如果没有统一的代码规范，那么每个人的代码必定会风格迥异。

且不说会存在多个人同时开发同一模块的情况，即使是分工十分明晰的，等到要整合代码的时候也有够头疼的了。

大多数情况下，并非程序中有复杂的算法或是复杂的逻辑，而是去读别人的代码实在是一件痛苦的事情，统一的风格使得代码可读性大大提高了，人们看到任何一段代码都会觉得异常熟悉，显然的，规范的代码在团队的合作开发中是非常有益而且必要的。

#### 3.1.2 规范的代码可以减少bug处理 ####

> 很多IT人士将程序员比做民工，这也的确非常的形象，就像刚才提到的，复杂的算法或逻辑只占项目中很小的比例，大多仅仅是垒代码的工作。

可是越是简单，测试的bug反而是越多，而且是无穷无尽的bug，这里很大的程度上是由于代码不规范所致。 没有规范的对输入输出参数的规范，没有规范的异常处理，没有规范的日志处理等等，不但导致了我们总是出现类似空指针这样低级的bug而且还很难找到引起bug的原因，相反，在规范的开发中，bug不但可以有效减少，查找bug也变得轻而易举， 规范不是对开发的制约，而确实是有助于提高开发效率的。

#### 3.1.3 规范的代码可以降低维护成本 ####

> 随着我们项目经验的累积，会越来越重视后期维护的成本，而开发过程中的代码质量直接影响着维护的成本，因此，我们不得不从开发时便小心翼翼。

在第一点中曾提到，规范的代码大大提高了程序的可读性，几乎所有的程序员都曾做过维护的工作，不用多说，可读性高的代码维护成本必然会大大降低。

但是，维护工作不仅仅是读懂原有代码，而是需要在原有代码基础上作出修改，我们可以先想像没有统一风格的情况下，A完成开发以后，B进行维护加一段代码，过一段时间C又加一段代码。。。。。。直到有一天X看到那一大堆乱码想死的心都有了，维护也就进行不下去了。

因此，统一的风格有利于长期的维护，另外，好的代码规范会对方法的度量、类的度量以及程序耦合性作出约束，这样不会出现需要修改一个上千行的方法或者去扩展一个没有接口的类的情况，规范的代码对程序的扩展性提高，无疑也是对维护人员的一个奖励。

#### 3.1.4 规范的代码有助于代码审查 ####

> 一些公司里面会定期进行代码审查的，这样可以及时纠正一些错误，而且可以对开发人员的代码规范作出监督

团队的代码审查同时也是一个很好的学习机会，对成员的进步也是很有益的，但是，开发随意，加重的代码审查的工作量及难度，并且使得代码审查工作没有根据，浪费了大量的时间却收效甚微，代码规范不仅使得开发统一，减少审查监督，而且让代码审查有据可查，大大提高了审查效率和效果，同时代码审查也有助于代码规范的实施，一举多得，何乐而不为呢。

#### 3.1.5 规范代码有助于养成代码规范的习惯 ####

> 有助于程序员自身的成长 即使明白代码规范的好处，但是有的迫于项目压力，有的因为繁琐的规范作出很多额外的工作，更有的不重视维护的问题，而很难贯彻代码规范。

那么，我们需要了解，规范开发最大的受益人其实是自己！你有没有花费很多的时候查找自己的代码呢？尤其是出现bug的时候需要逐行的debug？自己写的代码乱了头绪的确实也见了不少，我们应该做的就是规范开发，减少自己出现的错误，很多时候项目的压力一部分也是由于前期开发中遗留的众多的问题。

还有的人觉得自己可以完成高难度的算法，就认为自己能力很强，不把规范放在眼里，很多人确实是这样，追求个性，大概让别人看他的代码一头雾水更觉得得意，殊不知复杂的算法确实可以体现你个人的逻辑能力，但是绝不代表你的开发水平，我们知道一些开源项目，一些大师级人物写得程序都是极其规范的，并非规范了就代表高水平，实际上是规范的代码更有利于帮助你理解开发语言理解模式理解架构，能够帮助你快速提升开发水平，不明白这点，即使你写的再高明的算法，没准哪天也被当作乱码别处理掉。

## 4 如何规范代码 ##

> 如果代码不规范写的时间长了，在写规范的代码是很痛苦的，并且我们不清楚什么样的代码是规范的(每个公司的规范不一样)，可能到一个公司就需要新学习一套规范

我们可用借助一些权威的规范文档以及借助一些权威的工具让我们的代码更加规范，按照这些权威的文档或者工具的规范写出来的代码规范也是其他人能够认同的，下面我们介绍一些文档或者工具

### 4.1 阿里巴巴代码规范 ###

> 业界公认的代码规范手册（国内）当属阿里巴巴旗下出版的《Java 开发手册》，经过几个版本的迭代，最新手册为《Java开发手册(黄山版)》，更新时间为2022年2月3号

手册以 Java 开发者为中心视角，划分为编程规约、异常日志、 单元测试、 安全规约、 MySQL 数据库、 工程结构、 设计规约七个维度，再根据内容特征，细分成若干二级子目录，根据约束力强弱及故障敏感性，规约依次分为强制、推荐、参考三大类。对于规约条目的延伸信息中，“说明” 对规约做了适当扩展和解释；“正例” 提倡什么样的编码和实现方式；“反例”说明需要提防的雷区， 以及真实的错误案例。

### 4.2 代码规范工具 ###

> 在软件研发过程中，bug越早发现，成本越低

代码扫描和单元测试，就是在早期帮我们发现程序中问题的有效手段，代码扫描不仅能帮我们发现程序的漏洞，也能督促开发人员更规范优雅地写代码。

但是如何培养好的代码规范呢，刚开始是可能对于很多代码规范不太了解，就可以采用一些代码规范工具帮助我们更好的培养好的代码规范，比如《阿里巴巴java开发手册》，sonar等代码质量管理平台等。

#### 4.2.1 阿里规范插件 ####

为了让开发者更加方便、快速将规范推动并实行起来，阿里巴巴基于手册内容，研发了一套自动化的IDE检测插件，于是在云栖大会上，发布了阿里人经过247天持续研发的阿里巴巴JAVA规约扫描插件——**Alibaba Java Coding Guidelines.**

该插件就是《阿里巴巴Java开发规约》的扩展，为了方便开发者，该插件作为一个IDE的插件形式，支持 IDEA 和Eclipse，当然也支持Android Studio（ Android Studio是基于IDEA的）。

#### 4.2.2 sonar ####

sonar是一款静态代码质量分析工具，支持Java、Python、PHP、JavaScript、CSS等25种以上的语言，而且能够集成在IDE、Jenkins、Git等服务中，方便随时查看代码质量分析报告。

#### 4.2.3 两个工具对比 ####

*  **Alibaba代码规范插件**：比较关心的是代码规范，编码风格上的，例如，命名规范，注释，代码行数等。
 *  **SonarLint**：比较关心代码正确性，存在的问题，风险，漏洞等，例如，重复代码，空指针，安全漏洞等。

所以，一般建议结合使用，使用前者来规范代码，使用后者来提前发现代码的问题，配合起来提高工程整体的代码质量，并且能够在编码阶段规避风险，提高程序的健壮性。

## 5 日志打印规范 ##

### 5.1 为什么需要日志 ###

> 通常，Java程序员在开发项目时都是依赖Eclipse/IDEA等集成开发工具的Debug 调试功能来跟踪解决Bug，但项目发布到了测试、生产环境怎么办？你有可能会说可以使用远程调试，但实际并不能允许让你这么做。

所以，日志的作用就是在测试、生产环境没有 Debug 调试工具时开发和测试人员定位问题的手段，日志打得好，就能根据日志的轨迹快速定位并解决线上问题，反之，日志输出不好，不仅无法辅助定位问题反而可能会影响到程序的运行性能和稳定性。

很多介绍 AOP 的地方都采用日志来作为介绍，实际上日志要采用切面的话是极其不科学的！对于日志来说，只是在方法开始、结束、异常时输出一些什么，那是绝对不够的，这样的日志对于日志分析没有任何意义。

如果在方法的开始和结束整个日志，那方法中呢？如果方法中没有日志的话，那就完全失去了日志的意义！如果应用出现问题要查找由什么原因造成的，也没有什么作用，这样的日志还不如不用！

### 5.2 日志有什么用 ###

> 不管是使用何种编程语言，日志输出几乎无处不再，总结起来，日志大致有以下几种用途：

*  **问题追踪**：辅助排查和定位线上问题，优化程序运行性能。
 *  **状态监控**：通过日志分析，可以监控系统的运行状态。
 *  **安全审计**：审计主要体现在安全上，可以发现非授权的操作。

### 5.3 日志框架选择 ###

#### 5.3.1 常用的日志框架 ####

> log4j、Logging、commons-logging、slf4j、logback，这些都经常用的，为什么有这么多日志技术，它们都是什么区别和联系呢

##### 5.3.1.1 Logging #####

这是 Java 自带的日志工具类，在 JDK 1.5 开始就已经有了，在 java.util.logging 包下，通常情况下，这个基本没什么人用了，了解一下就行。

##### 5.3.1.2 commons-logging #####

commons-logging 是日志的门面接口，它也是Apache 最早提供的日志门面接口，用户可以根据喜好选择不同的日志实现框架，而不必改动日志定义，这就是日志门面的好处，符合面对接口抽象编程。现在已经不太流行了，了解一下就行。

##### 5.3.1.3 Slf4j #####

> slf4j，英文全称为“Simple Logging Facade for Java”，为java提供的简单日志Facade。

Facade门面，更底层一点说就是接口，它允许用户以自己的喜好，在工程中通过slf4j接入不同的日志系统。

因此slf4j入口就是众多接口的集合，它不负责具体的日志实现，只在编译时负责寻找合适的日志系统进行绑定。具体有哪些接口，全部都定义在slf4j-api中，查看slf4j-api源码就可以发现，里面除了public final class LoggerFactory类之外，都是接口定义，因此slf4j-api本质就是一个接口定义。

##### 5.03.1.4 Log4j #####

> Log4j 是 Apache 的一个开源日志框架，也是市场占有率最多的一个框架。

注意：log4j 在 2015.08.05 这一天被 Apache 宣布停止维护了，用户需要切换到 Log4j2上面去。

##### 5.3.1.5 Log4j2 #####

> Apache Log4j 2是apache开发的一款Log4j的升级产品。

Log4j2与Log4j1发生了很大的变化，log4j2不兼容log4j1。

##### 5.3.1.6 Logback #####

Logback 是 Slf4j 的原生实现框架，同样也是出自 Log4j 一个人之手，但拥有比 log4j 更多的优点、特性和更做强的性能，现在基本都用来代替 log4j 成为主流。

Logback相对于log4j拥有更快的执行速度。基于我们先前在log4j上的工作，logback 重写了内部的实现，在某些特定的场景上面，甚至可以比之前的速度快上10倍，在保证logback的组件更加快速的同时，同时所需的内存更加少。

#### 5.3.2 日志框架怎么选 ####

> 选项太多了的后果就是选择困难症，我的看法是没有最好的，只有最合适的

*  commons-loggin、slf4j 只是一种日志抽象门面，不是具体的日志框架，log4j、logback 是具体的日志实现框架。
 *  在比较关注性能的地方，选择Logback或自己实现高性能Logging API可能更合适，推荐：`slf4j + logback`.
 *  在已经使用了Log4j的项目中，如果没有发现问题，继续使用可能是更合适的方式：推荐组合为：`slf4j + log4j2`。
 *  如果不想有依赖则使用java.util.logging或框架容器已经提供的日志接口。

#### 5.3.3 记录日志的时机 ####

在看线上日志的时候，我们可曾陷入到日志泥潭？该出现的日志没有，无用的日志一大堆，或者需要的信息分散在各个角落，特别是遇到紧急的在线bug时，有效的日志被大量无意义的日志信息淹没，焦急且无奈地浪费大量精力查询日志。那什么是记录日志的合适时机呢？

##### 5.3.3.1 编程语言提示异常 #####

今各类主流的编程语言都包括异常机制，业务相关的流行框架有完整的异常模块，这类捕获的异常是系统告知开发人员需要加以关注的，是质量非常高的报错，应当适当记录日志，根据实际结合业务的情况使用warn或者error级别。

##### 5.3.3.2 业务流程预期不符 #####

除开平台以及编程语言异常之外，项目代码中结果与期望不符时也是日志场景之一，简单来说所有流程分支都可以加入考虑，取决于开发人员判断能否容忍情形发生，常见的合适场景包括外部参数不正确，数据处理问题导致返回码不在合理范围内等等。

##### 5.3.3.3 系统核心角色，组件关键动作 #####

系统中核心角色触发的业务动作是需要多加关注的，是衡量系统正常运行的重要指标，建议记录INFO级别日志，比如电商系统用户从登录到下单的整个流程；微服务各服务节点交互；核心数据表增删改；核心组件运行等等，如果日志频度高或者打印量特别大，可以提炼关键点INFO记录，其余酌情考虑DEBUG级别。

##### 5.3.3.4 系统初始化 #####

系统或者服务的启动参数。核心模块或者组件初始化过程中往往依赖一些关键配置，根据参数不同会提供不一样的服务。务必在这里记录INFO日志，打印出参数以及启动完成态服务表述。

### 5.4 日志打印 ###

#### 5.4.1 日志变量定义 ####

> 日志变量往往不变，最好定义成final static，变量名用大写。

private static final Logger logger = LoggerFactory.getLogger(BatchPullConsumer.class);

通常一个类只有一个 `logger` 对象，如果有父类可以将 `logger` 定义在父类中。

日志变量类型定义为门面接口（如 slf4j 的 Logger），实现类可以是 Log4j、Logback 等日志实现框架，不要把实现类定义为变量类型，否则日志切换不方便，也不符合抽象编程思想。

#### 5.4.2 参数占位格式 ####

> 使用参数化形式\{\}占位，\[\]进行参数隔离

logger.debug("Save order with order no：[{}], and order amount：[{}]");
    logger.debug("Save order with order no：[{}], and order amount：[{}]");

这种可读性好，这样一看就知道\[\]里面是输出的动态参数，\{\}用来占位类似绑定变量，而且只有真正准备打印的时候才会处理参数，方便定位问题。

如果日志框架不支持参数化形式，且日志输出时不支持该日志级别时会导致对象冗余创建，浪费内存，此时就需要使用 isXXEnabled 判断，如：

if(logger.isDebugEnabled()){
        // 如果日志不支持参数化形式，debug又没开启，那字符串拼接就是无用的代码拼接，影响系统性能
        logger.debug("Save order with order no：" + orderNo + ", and order amount：" + orderAmount);
    }

至少 debug 级别是需要开启判断的，线上日志级别至少应该是 info 以上的。

#### 5.4.3 日志的基本格式 ####

> 日志输出主要在文件中，应包括以下内容：

*  日志时间
 *  日志级别主要使用
 *  调用链标识（可选）
 *  线程名称
 *  日志记录器名称
 *  日志内容
 *  异常堆栈（不一定有）

##### 5.4.3.1 日志时间 #####

作为日志产生的日期和时间，这个数据非常重要，一般精确到毫秒，由于线上一般配置为按天滚动日志文件，日期标识在文件名上，所以可以不放在这个时间中，使用 `HH:mm:ss.SSS` 格式即可，非要加上也未尝不可，格式推荐：`yyyy-MM-dd HH:mm:ss.SSS`。

##### 5.4.3.2 日志级别 #####

> 日志的输出都是分级别的，不同的设置不同的场合打印不同的日志。

*  DEBUG：DEUBG 级别的主要输出调试性质的内容，该级别日志主要用于在开发、测试阶段输出。
 *  INFO：INFO日志主要记录系统关键信息，旨在保留系统正常工作期间关键运行指标。
 *  WARN：WARN 级别的主要输出警告性质的内容，这些内容是可以预知且是有规划的。
 *  ERROR：ERROR 级别主要针对于一些不可预知的信息，诸如：错误、异常等。

#### 5.4.4 日志文件 ####

> 日志文件放置于固定的目录中，按照一定的模板进行命名，推荐的日志文件名称：

当前正在写入的日志文件名：<应用名>[-<功能名>].log
    需要保留历史的日志文件名：<应用名>[-<功能名>].log.<yyyy-MM-dd>

[7b8171988bab481ab10c76ca03ac8f3a.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/15/d6286ecc006f41ddad98022a812a65bc.png
[84b0bf621aea4b02b807dbe010936397.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/15/c72a94e523d644d5af250bf8a3d74aff.png