本文已参与掘金创作者训练营第三期「话题写作」赛道，详情查看：掘力计划｜创作者训练营第三期正在进行，「写」出个人影响力。
什么样的代码是可读性强的代码？者不仅仅是一个新手开发者焦虑的问题，也是多年开发经验的老鸟也会焦虑的问题。下面我就从代码命名 、代码注释、设计文档等几个方面说说我的理解。第一次写类似的文章，请多多指点！
代码命名
以 Java 开发者来说，代码命名是一个头疼的问题，因为名字这个东西 “仁者见仁智者见智”。不同的人有不同的理解。如何鉴别是一个比较好的命名呢？我的答案就是： “见名知意、通俗易懂”，用最常用的单词然后合理的组合即可。
类名
咱们类名通常是驼峰命名，首字母大写。例子：
ForceCode // 正例
forceCode // 反例
方法名和变量名
方法名，和变量名采用首字母小写的驼峰命名风格，例子：
localValue / getHttpMessage
包名
包名注意全部小写，分割符之间采用单词单数，例子：
org.springframework.beans
各层命名参考
A) Service/DAO 层方法命名规约
1） 获取单个对象的方法用 get 做前缀。
2） 获取多个对象的方法用 list 做前缀，复数结尾，如：listObjects。
3） 获取统计值的方法用 count 做前缀。
4） 插入的方法用 save/insert 做前缀。
5） 删除的方法用 remove/delete 做前缀。
6） 修改的方法用 update 做前缀。
B) 领域模型命名规约
1） 数据对象：xxxDO，xxx 即为数据表名。
2） 数据传输对象：xxxDTO，xxx 为业务领域相关的名称。
3） 展示对象：xxxVO，xxx 一般为网页名称。
4） POJO 是 DO/DTO/BO/VO 的统称，禁止命名成 xxxPOJO。
代码注释
动手设代码之前，大家一定要先把对应的需求逻辑先梳理一遍，最好形成文档或者流程图之类的再来开发，要做到“想好了做”。不然做好了后面忘记了前面，代码就越堆越多。
可以把这些关键的的点都在注释中备注一下，记住：“注释只是代码关键逻辑的补充描述”，我不建议在代码中进行长篇大论。这些应该放在设计文档中或者或者写在 wiki 中。
注释分为三种：文档注释，行注释，多行注释，标记。
怎么算是一个合格的注释呢？我觉得应该是能够辅助代码让读者快速掌握开发者真正表达的意图的注释就是合格的注释；简而言之就是说能够在关键的代码位置进行补充描述让读者更加容易理解代码逻辑。
文档注释
对于一个 Java 文件首先需要有文档注释， 文档注释我觉得主要是说清楚这个类是做什么的；这个类是谁写的，或者多个人写的；以及创建时间，修改记录等。
/**
* 测试类
*
* @auther xx
* @date 2021-08-17
*/
public class Test {
}
行注释
方法内部单行注释，在被注释语句上方另起一行，使用//注释。方法内部多行注释使用/* */注释，注意与代码对齐。
行注释是咱们用得最多得注释。在注释得时候一定要注意用词一定要简单，如果英文不是特别标准尽量使用中文，以免误导读者。最后自己写的注释在 code review 中一定要看一下看自己能否读懂，或者互相阅读代码的时候判断是否注释能够帮助读者更好地阅读代码。
特殊注释标记
特殊标记最常用的就是 todo 、fixme 对于这类标记需要写清楚标记的原因、标记人、预计处理时间即可。例子：
// todo 这里还有补充的订单回退逻辑 xx 2021-08-17
// fixme 这里订单处理逻辑无法异常回退 xx 2021-08-17
设计文档
我觉得大多数开发者和我有类似的情况，“让我写代码没问题，让我写文档完全为难我了”。为什么有这样的问题因为我们觉得自己写的逻辑要么本身就比较乱，或者是在以前的功能上拓展的不愿意去梳理以前的逻辑，或者就是说这块功能比较简单。其实我们开发过程中其实有很多文档是必不可少的。
- 需求文档（PRD）
- 数据库设计文档（E-R 图）
- 设计文档（核心功能流程图，数据约束，外部依赖）
- 代码
- 代码审查日志
- 测试用例
- 运维日志
