code S| 关于代码风格与代码规范的二三事

date: 2017-12-19 14:07:34
title: code S: code style & code standard
description: 关于代码风格与代码规范的二三事

先解释一下标题, code S 既可以是 code style, 也可以是 code standard, 大部分情况是兼而有之. 无论是 style 来表达 编程之美 或者 编程即艺术, 还是用 standard 来 约束, 都表达了 code 应该是 有迹可循 的.

关于 code S 这个话题, 一个相关的是最近很火的 阿里巴巴 Java 开发手册. 作为 phper, 自然是 PSR. 另一个值得推荐的是 程序员DD - 翟永超的公众号 中的专题文章 -- 程序员你为什么那么累.

本篇参考了大部分 程序员DD - 翟永超的公众号 中的文章, 推荐移步一观.

首先是需要考虑的几个问题:

是不是觉得很矛盾, 一方面工作不复杂, 一方面却累成狗
大部分人的大部分时间都是在 定位问题 + 改代码, 真正开发的时间并不多
simple is not easy
对于个人来说, 技术很重要. 但是对于工作来说, 编码的习惯比技术更加主要
不管接手任何项目组, 第一步就是制定代码框架, 制定项目组的开发规范, 把代码量减下去

对比:

原始 规范后

这样做的思想也很简单: 实际上干活的就只有一行, 其他都和业务代码没有一毛钱关系.

实际效果也很明显: 代码量减少 -> 加班减少 -> 我愿意

PS: 技术精简使用的 AOP, 其中 Lang 会使用 ThreadLocal 处理掉.

详细议题:

• 接口定义规范
• controller规范
• 日志规范
• 异常处理规范
• 国际化规范
• 参数校验规范
• 工具类规范
• 函数编写建议
• 配置建议

规范里面大部分是 不要做的项多, 要做的比较少, 落地比较容易
代码最主要的不是性能，而是可读性, 有了可读性才有维护性
我觉得我的编码习惯比技术更有价值
傻瓜都能写出计算机可以读懂的代码, 只有优秀的程序员才能写出人能读懂的代码

程序猿不招妹子们喜爱的根本原因在于追求了错误的目标：更短、更小、更快。

接口定义规范

• 返回格式统一, 不要使用 map，json，object 等类型, 统一使用 ResultBean / PageResultBean
• 考虑失败情况: 被 ResultBean 封装掉
• 出现业务无关输入参数, 比如上面的 Lang 使用 ThreadLocal 优化掉
• 出现复杂输入参数, 比如 json, 可读性极差, 应该定义为对应的 bean
• 没有返回应该返回的数据, 这需要编程经验, 不返回或者返回True 都是不应该的. 别人要不要是别人的事情, 你该返回的还是应该返回

ResultBean: code(状态) + msg, 并处理 Exception

统一的好处:

• 避免很多无用返工和可能出现的问题
• 代码可读性
• 利于利用 AOP/自动化测试这些额外工作

controller规范

上面的规范要继承, 还需要注意以下几点

• ResultBean/PageResultBean 是 controller 专用的, 不允许往后传
• Controller 做参数格式的转换, 不允许把 json/map 这类对象传到 services 去, 也不允许 services 返回 json/map
• 参数中一般情况不允许出现 Request/Response 这些对象
• 不需要打印日志 -> AOP, 大部分日志 Service 层打印

json/map, 格式灵活, 但是可读性差 -> bean, 看着工作量多了, 但代码清晰多了

AOP:

• 打印日志
• 捕获异常, 异常分为已知异常和未知异常, 未知异常添加邮件通知之类的, 不同异常返回不同返回码
• 配置 or 代码 -> 配置优先

日志规范

日志落地问题:

• 没有日志功能一样跑 -> 出了问题没日志, 只能再加
• 节点多 -> 日志要一个一个翻

日志至少要求:

• 能找到机器
• 能找到用户做了什么: log4j 使用 MDC 使日志记录是带上 user 标识

// nginx -> 简单配置返回节点
add_header X-Slave $upstream_addr;

打印日志要求:

• 修改操作必须打上日志
• 条件分支必须打上条件值, 重要参数必须打印
• 数据量大必须打印数据数量

培养日志习惯:

• 不要依赖 debug, 多依赖日志
• 代码提交前先跑一遍看看日志是否看得懂

日志等级 -> 不是很关注 -> 简单规则, 更好落实

异常处理规范

出了异常不知道 -> 闹大了被投诉
出了问题无法定位原因
任何规定都无法保证一定不会发生错误 -> 我只相信代码

• 开发组长定义好异常, 其实没几种, 太细了很难落地
• 绝大部分场景, 不允许捕获异常, 不要乱加空判断 -> 自以为写了 「健壮」 的代码 -> 尽早让错误抛出来
• 后台(任务队列)异常一定要加通知机制, 要第一时间知道异常

国际化规范 & 参数校验规范

• 业务代码里面不要出现和业务无关的东西, 如 local/MessageSource -> ThreadLocal
• 国际化信息放哪: url vs cookie -> url 比较 low 还容易出问题
• 静态方法注入实现参数校验
• 参数非法时打印 key/value 出来

PS: 代码写得不够好, 才需要多加注释来凑

工具类规范 - 动态代理

• 定义注解 -> 需要常驻内存支持, 不然每次运行都需要消耗性能来解析注解
• 注解解析 -> Reflections -> 生成动态代理
• 动态代理 -> 注册到 spring 容器
• 定义默认的 RestTemplate 处理请求类 -> 注册到 spring 容器 -> RestTemplate 可以添加认证
• JUNIT 测试

函数编写建议

• 不要出现业务无关参数
• 避免使用 Map/Json 等复杂数据结构对象作为参数和结果
• 有明确的输入输出和方法名
• 把可能变化的地方封装成函数 -> 需求老变
• 编写能测试的函数

配置规范

• 先定义 bean -> 确定包含关系
• 使用代码生成 + 测试
• 业务开发 / 功能测试完毕 -> 定义配置文件, 格式推荐 JSON

禁忌:

• 读取配置和业务代码耦合
• 开发初期就定配置文件

应对需求变更

说的好像别人的需求就不会变动似的
正是因为需求变更不可避免, 所以我们才更应该把代码写简单, 以对付各种各样的需求变化

• 把代码写到最简单
• 把可能变化的封装成函数
• 多个功能中先做不会变的功能, 一个功能中先做不会变的部分
• 设计上多采取解耦的设计, 多引入「第三者」, 不要直接发生关系 -> IOC
• 数据结构上要考虑功能将来的扩展

要主动思考, 多走一步, 不要被动接受看到的需求, 要对需求的将来变化做好心中有数

工具类规范

定义自己的工具类, 尽量不要在业务代码里面直接调用第三方的工具类

• 字符串处理: 判断字符串为空
• 复制对象的属性和方法

抽象: 使用父类/接口
使用重载编写衍生函数组 -> 多参数数据类型
静态引入: 约定项目组使用的方法名
独立 / 框架级

抽象封装 / 参数优化